{ "openapi": "3.1.0", "info": { "title": "ArcPanel REST API v2", "version": "2", "description": "Resource API of an ArcPanel server, served by the panel at `/api/v2/` (port 8083 by default). Every call acts as the owner of the access key, with the role and the reach that user has in the panel: objects outside its reach answer `404`, refused actions `403`.\n\n**Authentication.** `Authorization: Bearer ACCESS_KEY_ID:SECRET_ACCESS_KEY`, an access key of the panel (Account → Access keys). The API must be on (`API_SYSTEM` 1 for the administrator's keys, 2 for every key) and accept the client's address (`API_ALLOWED_IP`). A key with permission sets may only run their commands. `v2-read` allows every read endpoint and `v2-write` every endpoint; each area also has its own set (`v2-accounts`, `v2-web`, and the sets of later areas). A change that touches another area needs that area's set too. API v1 refuses every set marked for v2. `GET /me` describes the key.\n\n**Pagination.** Every list accepts `limit` (1–1000) and `offset` (0 or more). `meta.total` is the number of items. Without `limit` the list is complete, as before pagination existed.\n\n**Dry run.** Every write accepts `?dry_run=1`: the request is validated, authorized and checked against the permission sets, and the answer lists the commands it would run, without running any.\n\n**Errors.** Every error answers `{\"error\": {\"code\": \"E_…\", \"message\": \"…\"}}`; `code` is one of `ErrorCode`. Validation errors add `fields`, refused permission sets add `commands`, a duplicate the server can point at adds `existing` (the path of that object, or a queued backup or restore task), and a failed step of a change adds `step` and the steps that ran before it (`applied`), which stay applied. File operations add the names that exist in the destination (`conflicts`) and, when they stop part-way, the path that failed (`path`) and the paths already finished (`done`).\n\n**Headers.** Every answer carries `ArcPanel-Version` and `X-Request-Id` (the client's own value, or a new one). `429` carries `Retry-After`; `201` and `202` carry `Location`. Each key may make 60 requests a minute; ten failed authentications a minute block the client's address for a minute.\n\n**Compatibility.** Within v2 the document only grows: new operations, new optional fields, new enum values. Clients should ignore unknown fields." }, "servers": [ { "url": "https://{host}:{port}/api/v2", "description": "An ArcPanel server", "variables": { "host": { "default": "panel.example.com" }, "port": { "default": "8083" } } } ], "paths": { "/access-key-sets": { "get": { "operationId": "listAccessKeySets", "description": "The sets the caller may give to a key of `user` (default: the owner\nof the calling key): those the owner may have, and, for a key with\nsets, only those the calling key holds.", "summary": "List the permission sets a key may give", "tags": [ "Access keys" ], "parameters": [ { "name": "user", "in": "query", "description": "The owner of the keys to create.", "schema": { "type": "string", "pattern": "^[[:alnum:]][-.\\w]*$", "maxLength": 32 } }, { "name": "limit", "in": "query", "description": "Page size, from 1 to 1000. Without it the list is complete.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "offset", "in": "query", "description": "Items to skip. Used when `limit` is set; 0 when omitted.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Array of `AccessKeySet`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AccessKeySet" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/backups": { "get": { "operationId": "listAllBackups", "description": "Every user's backup archives for an administrator's key, those of the reseller\nand its customers for a reseller's key; a user's key answers 403\n(`listBackups` covers it). Sorted by user, then name. With\n`updated_since`, only the users whose backup archives changed at or after that\ntime are returned, each with all its backup archives: `meta.as_of` is the next\n`updated_since`, `meta.users` every user in scope and\n`meta.changed_users` the users returned (E43 B2).", "summary": "List the backup archives of every user", "tags": [ "Backups" ], "responses": { "200": { "description": "Array of `Backup`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Backup" } }, "meta": { "$ref": "#/components/schemas/CrossUserListMeta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "parameters": [ { "name": "user", "in": "query", "description": "One user in the scope of the key; the list then holds only that user. A user outside the scope answers 404.", "schema": { "type": "string", "pattern": "^[[:alnum:]][-.\\w]{0,28}[[:alnum:]]$" } }, { "name": "updated_since", "in": "query", "description": "ISO 8601 time, UTC without an offset: only the users whose objects of this kind changed at or after it, each with all its objects. Use the `meta.as_of` of the previous first page.", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "description": "Page size, from 1 to 1000. Without it the list is complete.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "offset", "in": "query", "description": "Items to skip. Used when `limit` is set; 0 when omitted.", "schema": { "type": "integer", "minimum": 0 } } ] } }, "/cron-jobs": { "get": { "operationId": "listAllCronJobs", "description": "Every user's cron jobs for an administrator's key, those of the reseller\nand its customers for a reseller's key; a user's key answers 403\n(`listCronJobs` covers it). Sorted by user, then id. With\n`updated_since`, only the users whose cron jobs changed at or after that\ntime are returned, each with all its cron jobs: `meta.as_of` is the next\n`updated_since`, `meta.users` every user in scope and\n`meta.changed_users` the users returned (E43 B2). `meta.timezone` is the\nserver's time zone.", "summary": "List the cron jobs of every user", "tags": [ "Cron" ], "responses": { "200": { "description": "Array of `CronJob`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CronJob" } }, "meta": { "$ref": "#/components/schemas/CrossUserListMeta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "parameters": [ { "name": "user", "in": "query", "description": "One user in the scope of the key; the list then holds only that user. A user outside the scope answers 404.", "schema": { "type": "string", "pattern": "^[[:alnum:]][-.\\w]{0,28}[[:alnum:]]$" } }, { "name": "updated_since", "in": "query", "description": "ISO 8601 time, UTC without an offset: only the users whose objects of this kind changed at or after it, each with all its objects. Use the `meta.as_of` of the previous first page.", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "description": "Page size, from 1 to 1000. Without it the list is complete.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "offset", "in": "query", "description": "Items to skip. Used when `limit` is set; 0 when omitted.", "schema": { "type": "integer", "minimum": 0 } } ] } }, "/databases": { "get": { "operationId": "listAllDatabases", "description": "Every user's databases for an administrator's key, those of the reseller\nand its customers for a reseller's key; a user's key answers 403\n(`listDatabases` covers it). Sorted by user, then name. With\n`updated_since`, only the users whose databases changed at or after that\ntime are returned, each with all its databases: `meta.as_of` is the next\n`updated_since`, `meta.users` every user in scope and\n`meta.changed_users` the users returned (E43 B2).", "summary": "List the databases of every user", "tags": [ "Databases" ], "responses": { "200": { "description": "Array of `Database`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Database" } }, "meta": { "$ref": "#/components/schemas/CrossUserListMeta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "parameters": [ { "name": "user", "in": "query", "description": "One user in the scope of the key; the list then holds only that user. A user outside the scope answers 404.", "schema": { "type": "string", "pattern": "^[[:alnum:]][-.\\w]{0,28}[[:alnum:]]$" } }, { "name": "updated_since", "in": "query", "description": "ISO 8601 time, UTC without an offset: only the users whose objects of this kind changed at or after it, each with all its objects. Use the `meta.as_of` of the previous first page.", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "description": "Page size, from 1 to 1000. Without it the list is complete.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "offset", "in": "query", "description": "Items to skip. Used when `limit` is set; 0 when omitted.", "schema": { "type": "integer", "minimum": 0 } } ] } }, "/docker-catalog": { "get": { "operationId": "listDockerCatalog", "summary": "List catalog apps visible to the caller", "tags": [ "Docker catalog" ], "responses": { "200": { "description": "Array of `DockerCatalogEntry`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DockerCatalogEntry" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/docker-catalog/{slug}": { "get": { "operationId": "getDockerCatalogApp", "summary": "Get a catalog app manifest", "tags": [ "Docker catalog" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "version", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^[0-9A-Za-z][0-9A-Za-z._+-]{0,39}$" } } ], "responses": { "200": { "description": "`DockerCatalogApp`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DockerCatalogApp" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/malware": { "get": { "operationId": "getMalwareSummary", "description": "One row per user of the principal's tree: open findings by severity,\nquarantined files and the newest scan. Administrators and resellers.", "summary": "Summarise the malware scan of the users", "tags": [ "Malware scan" ], "responses": { "200": { "description": "Array of `MalwareSummary`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MalwareSummary" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/me": { "get": { "operationId": "getMe", "description": "The access key of the request: its owner and role, its permission\nsets and the commands they allow (`*` when unrestricted), and the\nversions of the panel and of the API. Clients use it to check a\nprofile (E34 spec D12). `server_id` identifies the server: it stays\nthe same for every key of the server and changes when the machine is\ncloned with a new identity (E43 B1). `key_expires_at` and\n`key_allowed_ips` are the restrictions of the calling key.", "summary": "Who am I", "tags": [ "Account" ], "responses": { "200": { "description": "`Me`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Me" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/node-apps": { "get": { "operationId": "listAllNodeApps", "description": "Every user's Node.js apps for an administrator's key, those of the reseller\nand its customers for a reseller's key; a user's key answers 403\n(`listNodeApps` covers it). Sorted by user, then domain. With\n`updated_since`, only the users whose Node.js apps changed at or after that\ntime are returned, each with all its Node.js apps: `meta.as_of` is the next\n`updated_since`, `meta.users` every user in scope and\n`meta.changed_users` the users returned (E43 B2). The apps come from\ntheir records: the live state of pm2 (`runtime`, `status`, `online`,\n`reason`, `pid`, `cpu`, `memory_mb`, `restarts`, `uptime_seconds`) is\nnull; getNodeApp and listNodeApps answer it.", "summary": "List the Node.js apps of every user", "tags": [ "Node.js apps" ], "responses": { "200": { "description": "Array of `NodeApp`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/NodeApp" } }, "meta": { "$ref": "#/components/schemas/CrossUserListMeta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "parameters": [ { "name": "user", "in": "query", "description": "One user in the scope of the key; the list then holds only that user. A user outside the scope answers 404.", "schema": { "type": "string", "pattern": "^[[:alnum:]][-.\\w]{0,28}[[:alnum:]]$" } }, { "name": "updated_since", "in": "query", "description": "ISO 8601 time, UTC without an offset: only the users whose objects of this kind changed at or after it, each with all its objects. Use the `meta.as_of` of the previous first page.", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "description": "Page size, from 1 to 1000. Without it the list is complete.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "offset", "in": "query", "description": "Items to skip. Used when `limit` is set; 0 when omitted.", "schema": { "type": "integer", "minimum": 0 } } ] } }, "/notifications": { "get": { "operationId": "listNotifications", "description": "The notifications of the key's owner, newest first, as plain text.", "summary": "List notifications", "tags": [ "Notifications" ], "responses": { "200": { "description": "Array of `Notification`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Notification" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "parameters": [ { "name": "limit", "in": "query", "description": "Page size, from 1 to 1000. Without it the list is complete.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "offset", "in": "query", "description": "Items to skip. Used when `limit` is set; 0 when omitted.", "schema": { "type": "integer", "minimum": 0 } } ] }, "delete": { "operationId": "deleteAllNotifications", "summary": "Delete every notification", "tags": [ "Notifications" ], "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "204": { "description": "No content.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "parameters": [ { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ] } }, "/notifications/acknowledge": { "post": { "operationId": "acknowledgeAllNotifications", "summary": "Acknowledge every notification", "tags": [ "Notifications" ], "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "204": { "description": "No content.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "parameters": [ { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ] } }, "/notifications/{id}": { "delete": { "operationId": "deleteNotification", "summary": "Delete a notification", "tags": [ "Notifications" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "204": { "description": "No content.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/notifications/{id}/acknowledge": { "post": { "operationId": "acknowledgeNotification", "summary": "Acknowledge a notification", "tags": [ "Notifications" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "204": { "description": "No content.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/packages": { "get": { "operationId": "listPackages", "description": "Every package but `system` for an administrator, the packages a\nreseller may assign for a reseller.", "summary": "List packages", "tags": [ "Packages" ], "responses": { "200": { "description": "Array of `Package`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Package" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "parameters": [ { "name": "limit", "in": "query", "description": "Page size, from 1 to 1000. Without it the list is complete.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "offset", "in": "query", "description": "Items to skip. Used when `limit` is set; 0 when omitted.", "schema": { "type": "integer", "minimum": 0 } } ] }, "post": { "operationId": "createPackage", "description": "Fields left out take the values of the add form of the panel. A\nreseller's package is stored as RESELLER_NAME and may not exceed the\nreseller's own limits; the `reseller` settings are an administrator's.\nA repeated call answers 409 `E_EXISTS`.", "summary": "Create a package", "tags": [ "Packages" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorePackageRequest" } } } }, "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "201": { "description": "`Package`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Package" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" }, "Location": { "$ref": "#/components/headers/Location" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "parameters": [ { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ] } }, "/packages/{package}": { "get": { "operationId": "getPackage", "summary": "Get a package", "tags": [ "Packages" ], "parameters": [ { "name": "package", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`Package`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Package" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "operationId": "updatePackage", "description": "The fields left out keep their value; the package is applied to its\nusers. An administrator renames it with `name`.", "summary": "Update a package", "tags": [ "Packages" ], "parameters": [ { "name": "package", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePackageRequest" } } } }, "responses": { "200": { "description": "`Package`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Package" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "delete": { "operationId": "deletePackage", "description": "A package with users answers 409 `E_INUSE`; `default` cannot be deleted.", "summary": "Delete a package", "tags": [ "Packages" ], "parameters": [ { "name": "package", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "204": { "description": "No content.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/packages/{package}/copy": { "post": { "operationId": "copyPackage", "description": "Administrators only; the copy has the reseller, port, Node.js and\nDocker settings of the original.", "summary": "Copy a package", "tags": [ "Packages" ], "parameters": [ { "name": "package", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CopyPackageRequest" } } } }, "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "201": { "description": "`Package`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Package" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" }, "Location": { "$ref": "#/components/headers/Location" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/requests/{id}": { "get": { "operationId": "getRequest", "description": "What became of a write, found by its request id: the `X-Request-Id`\nof its answer, which is the client's own id when it is valid. A client\nwhose answer was lost asks here before it tries again (E43 B4). Writes\nof access keys are journaled for 7 days without their bodies; reads\nand dry runs are not. `state` is `running` for 15 minutes after the\nstart of a request without an end and `unknown` after that. A key sees\nthe requests of the keys of its own user, an administrator's key every\nrequest; any other id answers 404. When several requests share the id,\nthe latest is returned and `meta.duplicates` counts them. Every key may\ncall it, whatever its permission sets.", "summary": "Look up a request", "tags": [ "Requests" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`ApiRequest`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ApiRequest" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/search": { "get": { "operationId": "search", "description": "Objects whose name contains `q`, grouped by type in the order users,\nweb domains, DNS zones, DNS records, mail domains, mail accounts,\ndatabases, cron jobs; at most 50 per type. Types without a match are\nleft out. Users are found by name, full name or e-mail; the other\nobjects only for a single word (letters, digits, `.`, `@`, `_`, `-`).", "summary": "Search", "tags": [ "Search" ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "The text to find, 2 to 100 characters.", "schema": { "type": "string", "minLength": 2, "maxLength": 100 } } ], "responses": { "200": { "description": "Array of `SearchGroup`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SearchGroup" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/stats": { "get": { "operationId": "listStats", "description": "Administrators: the totals of the server; resellers: the totals of\ntheir account and their customers; users: 403. Newest first.", "summary": "List the monthly totals", "tags": [ "Statistics" ], "responses": { "200": { "description": "Array of `StatsMonth`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StatsMonth" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "parameters": [ { "name": "limit", "in": "query", "description": "Page size, from 1 to 1000. Without it the list is complete.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "offset", "in": "query", "description": "Items to skip. Used when `limit` is set; 0 when omitted.", "schema": { "type": "integer", "minimum": 0 } } ] } }, "/system/docker": { "get": { "operationId": "getDockerEngine", "summary": "Get the Docker engine", "tags": [ "Server" ], "responses": { "200": { "description": "`DockerEngine`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DockerEngine" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/system/docker/install": { "post": { "operationId": "installDockerEngine", "summary": "Install the Docker engine", "tags": [ "Server" ], "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "202": { "description": "`Task`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Task" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" }, "Location": { "$ref": "#/components/headers/Location" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "parameters": [ { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ] } }, "/system/firewall/bans": { "get": { "operationId": "listFirewallBans", "description": "Newest first.", "summary": "List the banned addresses", "tags": [ "Server" ], "responses": { "200": { "description": "Array of `FirewallBan`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FirewallBan" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "parameters": [ { "name": "limit", "in": "query", "description": "Page size, from 1 to 1000. Without it the list is complete.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "offset", "in": "query", "description": "Items to skip. Used when `limit` is set; 0 when omitted.", "schema": { "type": "integer", "minimum": 0 } } ] }, "post": { "operationId": "createFirewallBan", "description": "Adds `ip` to the ban list of `chain`. An address banned in that chain\nalready answers `409 E_EXISTS`.", "summary": "Ban an address", "tags": [ "Server" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreFirewallBanRequest" } } } }, "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "201": { "description": "`FirewallBan`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FirewallBan" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" }, "Location": { "$ref": "#/components/headers/Location" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "parameters": [ { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ] } }, "/system/firewall/bans/{chain}/{ip}": { "delete": { "operationId": "deleteFirewallBan", "description": "`ip` is the banned address or network, URL-encoded (`2001%3Adb8%3A%3A7`,\n`198.51.100.0%2F24`).", "summary": "Unban an address", "tags": [ "Server" ], "parameters": [ { "name": "chain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "ip", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "204": { "description": "No content.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/system/firewall/ipsets": { "get": { "operationId": "listFirewallIpsets", "description": "Sorted by name.", "summary": "List the IPset lists of the firewall", "tags": [ "Server" ], "responses": { "200": { "description": "Array of `FirewallIpset`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FirewallIpset" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "parameters": [ { "name": "limit", "in": "query", "description": "Page size, from 1 to 1000. Without it the list is complete.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "offset", "in": "query", "description": "Items to skip. Used when `limit` is set; 0 when omitted.", "schema": { "type": "integer", "minimum": 0 } } ] }, "post": { "operationId": "createFirewallIpset", "description": "A rule uses an active IPv4 list as `source` `ipset:NAME`. A name that\nexists answers `409 E_EXISTS`.", "summary": "Add an IPset list", "tags": [ "Server" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreFirewallIpsetRequest" } } } }, "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "201": { "description": "`FirewallIpset`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FirewallIpset" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" }, "Location": { "$ref": "#/components/headers/Location" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "parameters": [ { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ] } }, "/system/firewall/ipsets/{name}": { "delete": { "operationId": "deleteFirewallIpset", "summary": "Delete an IPset list", "tags": [ "Server" ], "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "204": { "description": "No content.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/system/firewall/rules": { "get": { "operationId": "listFirewallRules", "description": "In the order they apply. A rule's id is its position: moving a rule or\ndeleting one before it changes it.", "summary": "List the firewall rules", "tags": [ "Server" ], "responses": { "200": { "description": "Array of `FirewallRule`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FirewallRule" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "parameters": [ { "name": "limit", "in": "query", "description": "Page size, from 1 to 1000. Without it the list is complete.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "offset", "in": "query", "description": "Items to skip. Used when `limit` is set; 0 when omitted.", "schema": { "type": "integer", "minimum": 0 } } ] }, "post": { "operationId": "createFirewallRule", "description": "The rule goes after the last one; its id is that position. A rule\nwith the same action, protocol, port and source answers `409\nE_EXISTS` with `existing`. Comments of the form `arcpanel-port-…`\nbelong to the port registry and are refused.", "summary": "Add a firewall rule", "tags": [ "Server" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreFirewallRuleRequest" } } } }, "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "201": { "description": "`FirewallRule`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FirewallRule" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" }, "Location": { "$ref": "#/components/headers/Location" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "parameters": [ { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ] } }, "/system/firewall/rules/{rule}": { "get": { "operationId": "getFirewallRule", "description": "The id is the rule's position in the rule order.", "summary": "Get a firewall rule", "tags": [ "Server" ], "parameters": [ { "name": "rule", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`FirewallRule`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FirewallRule" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "operationId": "updateFirewallRule", "description": "Fields left out keep their value; the id (the rule's position) does\nnot change. The port registry's rules answer `403`.", "summary": "Update a firewall rule", "tags": [ "Server" ], "parameters": [ { "name": "rule", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateFirewallRuleRequest" } } } }, "responses": { "200": { "description": "`FirewallRule`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FirewallRule" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "delete": { "operationId": "deleteFirewallRule", "description": "The rules after it move up one position, so their ids drop by one.\nThe port registry's rules answer `403`.", "summary": "Delete a firewall rule", "tags": [ "Server" ], "parameters": [ { "name": "rule", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "204": { "description": "No content.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/system/firewall/rules/{rule}/move": { "post": { "operationId": "moveFirewallRule", "description": "Swaps the rule with the one before it (`up`) or after it (`down`): the\ntwo exchange their ids, which are their positions. Answers the rule\nwith its new id; `Content-Location` names its new path (not `Location`,\nwhich PHP would turn into a `302` redirect). The port registry's rules\nmove too.", "summary": "Move a firewall rule", "tags": [ "Server" ], "parameters": [ { "name": "rule", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoveFirewallRuleRequest" } } } }, "responses": { "200": { "description": "`FirewallRule`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FirewallRule" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" }, "Content-Location": { "description": "The path of the moved rule under its new id (E34 batch 6 D59); absent with `dry_run`.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/system/firewall/rules/{rule}/suspend": { "post": { "operationId": "suspendFirewallRule", "description": "The id is the rule's position. Nothing runs when the rule is\nsuspended already. The port registry's rules answer `403`.", "summary": "Suspend a firewall rule", "tags": [ "Server" ], "parameters": [ { "name": "rule", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "`FirewallRule`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FirewallRule" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/system/firewall/rules/{rule}/unsuspend": { "post": { "operationId": "unsuspendFirewallRule", "description": "The id is the rule's position. Nothing runs when the rule is active\nalready. The port registry's rules answer `403`.", "summary": "Unsuspend a firewall rule", "tags": [ "Server" ], "parameters": [ { "name": "rule", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "`FirewallRule`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FirewallRule" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/system/graphs": { "get": { "operationId": "listGraphs", "description": "Load, memory, network, web, mail, database and other graphs that the\nserver records.", "summary": "List the server graphs", "tags": [ "Server" ], "responses": { "200": { "description": "Array of `Graph`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Graph" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "parameters": [ { "name": "limit", "in": "query", "description": "Page size, from 1 to 1000. Without it the list is complete.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "offset", "in": "query", "description": "Items to skip. Used when `limit` is set; 0 when omitted.", "schema": { "type": "integer", "minimum": 0 } } ] } }, "/system/graphs/{graph}": { "get": { "operationId": "getGraph", "description": "The data points of one graph for `period` (default `daily`), with the\nnames of its series and the unit of their values.", "summary": "Get the data of a server graph", "tags": [ "Server" ], "parameters": [ { "name": "graph", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "period", "in": "query", "description": "The time span of the series: a day (default), a week, a month, a year, two or three years.", "schema": { "type": "string", "enum": [ "daily", "weekly", "monthly", "yearly", "biennially", "triennially" ] } } ], "responses": { "200": { "description": "`GraphData`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/GraphData" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/system/interfaces": { "get": { "operationId": "listInterfaces", "description": "The choices of `interface` in createIp.", "summary": "List the network interfaces of the server", "tags": [ "Server" ], "responses": { "200": { "description": "Array of `NetworkInterface`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/NetworkInterface" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "parameters": [ { "name": "limit", "in": "query", "description": "Page size, from 1 to 1000. Without it the list is complete.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "offset", "in": "query", "description": "Items to skip. Used when `limit` is set; 0 when omitted.", "schema": { "type": "integer", "minimum": 0 } } ] } }, "/system/ips": { "get": { "operationId": "listIps", "summary": "List the IP addresses of the server", "tags": [ "Server" ], "responses": { "200": { "description": "Array of `Ip`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Ip" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "parameters": [ { "name": "limit", "in": "query", "description": "Page size, from 1 to 1000. Without it the list is complete.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "offset", "in": "query", "description": "Items to skip. Used when `limit` is set; 0 when omitted.", "schema": { "type": "integer", "minimum": 0 } } ] }, "post": { "operationId": "createIp", "description": "`interface` is one of listInterfaces. An address the server already\nhas answers `409 E_EXISTS` with `existing`.", "summary": "Add an IP address", "tags": [ "Server" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreIpRequest" } } } }, "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "201": { "description": "`Ip`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Ip" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" }, "Location": { "$ref": "#/components/headers/Location" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "parameters": [ { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ] } }, "/system/ips/refresh": { "post": { "operationId": "refreshIps", "description": "Runs `v-update-sys-ip`, which reads the addresses of the network\ninterfaces again, and answers the addresses.", "summary": "Refresh the IP addresses", "tags": [ "Server" ], "responses": { "200": { "description": "Array of items; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "string" } } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "parameters": [ { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ] } }, "/system/ips/{ip}": { "get": { "operationId": "getIp", "summary": "Get an IP address", "tags": [ "Server" ], "parameters": [ { "name": "ip", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`Ip`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Ip" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "operationId": "updateIp", "description": "`owner`, `shared`, `name` and `nat`; fields left out keep their value,\nand only a changed field runs its command, in the order of the page.", "summary": "Update an IP address", "tags": [ "Server" ], "parameters": [ { "name": "ip", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateIpRequest" } } } }, "responses": { "200": { "description": "`Ip`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Ip" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "delete": { "operationId": "deleteIp", "summary": "Delete an IP address", "tags": [ "Server" ], "parameters": [ { "name": "ip", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "204": { "description": "No content.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/system/packages": { "get": { "operationId": "listSystemPackages", "description": "The catalog of runtimes and tools that administrators install from the\ndistribution's archive, with their state, version and the web domains\nthat need them.", "summary": "List the system packages", "tags": [ "Server" ], "responses": { "200": { "description": "Array of `SystemPackage`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SystemPackage" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "parameters": [ { "name": "limit", "in": "query", "description": "Page size, from 1 to 1000. Without it the list is complete.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "offset", "in": "query", "description": "Items to skip. Used when `limit` is set; 0 when omitted.", "schema": { "type": "integer", "minimum": 0 } } ] } }, "/system/packages/{slug}": { "post": { "operationId": "installSystemPackage", "description": "Installs the distribution packages of a catalog entry as the system\ntask. An entry that is installed answers `409 E_EXISTS`, one the\nrelease of the server does not have `422`; another running system\ntask answers `409 E_INUSE` with `existing`.", "summary": "Install a system package", "tags": [ "Server" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "202": { "description": "`Task`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Task" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" }, "Link": { "$ref": "#/components/headers/Link" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "delete": { "operationId": "removeSystemPackage", "description": "Removes an entry that the panel installed, as the system task. An entry\ninstalled by the system, or needed by web domains, answers `403`;\nanother running system task answers `409 E_INUSE` with `existing`.", "summary": "Remove a system package", "tags": [ "Server" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "202": { "description": "`Task`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Task" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" }, "Link": { "$ref": "#/components/headers/Link" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/system/php/profiles": { "get": { "operationId": "listPhpProfiles", "summary": "List the PHP-FPM profiles", "tags": [ "Server" ], "responses": { "200": { "description": "Array of `PhpProfile`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PhpProfile" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "parameters": [ { "name": "limit", "in": "query", "description": "Page size, from 1 to 1000. Without it the list is complete.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "offset", "in": "query", "description": "Items to skip. Used when `limit` is set; 0 when omitted.", "schema": { "type": "integer", "minimum": 0 } } ] }, "post": { "operationId": "createPhpProfile", "description": "A name in use answers `409 E_EXISTS`; relations the command checks\n(spare servers, upload limits) answer `422 E_INVALID`.", "summary": "Create a PHP-FPM profile", "tags": [ "Server" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhpProfileRequest" } } } }, "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "201": { "description": "`PhpProfile`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PhpProfile" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" }, "Location": { "$ref": "#/components/headers/Location" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "parameters": [ { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ] } }, "/system/php/profiles/{profile}": { "get": { "operationId": "getPhpProfile", "summary": "Get a PHP-FPM profile", "tags": [ "Server" ], "parameters": [ { "name": "profile", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`PhpProfile`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PhpProfile" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "updatePhpProfile", "description": "Rewrites the pool of every web domain on the profile and reloads PHP-FPM;\nwhen a version does not run afterwards, the previous profile comes back\n(`500 E_RESTART`).", "summary": "Change a PHP-FPM profile", "tags": [ "Server" ], "parameters": [ { "name": "profile", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhpProfileRequest" } } } }, "responses": { "200": { "description": "`PhpProfile`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PhpProfile" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "delete": { "operationId": "deletePhpProfile", "description": "The `default` profile cannot be deleted (`403`). A profile that web\ndomains use or packages name answers `409 E_INUSE` unless `force=1`,\nwhich moves the domains to `default` and removes it from the packages.", "summary": "Delete a PHP-FPM profile", "tags": [ "Server" ], "parameters": [ { "name": "profile", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "force", "in": "query", "schema": { "type": "boolean", "default": false } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "204": { "description": "No content", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/system/php/versions": { "get": { "operationId": "listPhpVersions", "description": "Every version of the panel's catalog and every installed one, oldest\nfirst, with its support status, end of life, whether it may be\ninstalled and the web domains that use it.", "summary": "List the PHP versions", "tags": [ "Server" ], "responses": { "200": { "description": "Array of `PhpVersion`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PhpVersion" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "parameters": [ { "name": "limit", "in": "query", "description": "Page size, from 1 to 1000. Without it the list is complete.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "offset", "in": "query", "description": "Items to skip. Used when `limit` is set; 0 when omitted.", "schema": { "type": "integer", "minimum": 0 } } ] } }, "/system/php/versions/{php}": { "get": { "operationId": "getPhpVersion", "summary": "Get a PHP version", "tags": [ "Server" ], "parameters": [ { "name": "php", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`PhpVersion`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PhpVersion" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "installPhpVersion", "description": "Installs the version from the PHP repository of the server as the\nsystem task. An installed version answers `409 E_EXISTS`, one at its\nend of life `422`, one the repository does not have `404`; another\nrunning system task answers `409 E_INUSE` with `existing`.", "summary": "Install a PHP version", "tags": [ "Server" ], "parameters": [ { "name": "php", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "202": { "description": "`Task`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Task" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" }, "Location": { "$ref": "#/components/headers/Location" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "delete": { "operationId": "removePhpVersion", "description": "Removes an installed version with its extensions, as the system task.\nThe default version and a version that web domains use answer `403`.", "summary": "Remove a PHP version", "tags": [ "Server" ], "parameters": [ { "name": "php", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "202": { "description": "`Task`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Task" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" }, "Location": { "$ref": "#/components/headers/Location" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/system/php/versions/{php}/extensions": { "get": { "operationId": "listPhpExtensions", "description": "The extension catalog entries that apply to the version with their\nstate for PHP-FPM and the command line, then the modules enabled on\nthe server that the catalog does not list (`catalog` false).", "summary": "List the extensions of a PHP version", "tags": [ "Server" ], "parameters": [ { "name": "php", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size, from 1 to 1000. Without it the list is complete.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "offset", "in": "query", "description": "Items to skip. Used when `limit` is set; 0 when omitted.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Array of `PhpExtension`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PhpExtension" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/system/php/versions/{php}/extensions/{name}": { "put": { "operationId": "setPhpExtension", "description": "`installed: true` installs a catalog extension as the system task\n(`202`). `fpm` and `cli` turn the module of an installed extension on\nor off for that SAPI; the answer is the extension. Required modules\ncannot be turned off (`403`), conflicting ones not on together\n(`409 E_INUSE`). A change that stops PHP-FPM is undone.", "summary": "Install or turn on and off a PHP extension", "tags": [ "Server" ], "parameters": [ { "name": "php", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetPhpExtensionRequest" } } } }, "responses": { "200": { "description": "`PhpExtension`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PhpExtension" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "delete": { "operationId": "removePhpExtension", "description": "Purges the package of a catalog extension as the system task. Required\nextensions, modules that ship with PHP and packages that others need\nanswer `403` or `409`.", "summary": "Remove a PHP extension", "tags": [ "Server" ], "parameters": [ { "name": "php", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "202": { "description": "`Task`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Task" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" }, "Location": { "$ref": "#/components/headers/Location" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/system/php/versions/{php}/ini/{sapi}": { "get": { "operationId": "getPhpIni", "description": "The directives of the php.ini form of PHP-FPM (`fpm`) or of the command\nline (`cli`) with their value and source; `?raw=1` adds the file.", "summary": "Get the php.ini of a PHP version", "tags": [ "Server" ], "parameters": [ { "name": "php", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "sapi", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "raw", "in": "query", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "`PhpIni`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PhpIni" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "replacePhpIni", "description": "The file is validated with the version's PHP first: syntax, the values\nof known directives, unknown directives (warnings), a start of PHP and,\nfor PHP-FPM, `php-fpm -t`. Errors answer `422 E_VALIDATION` with\n`fields` keyed by `line:`; warnings are saved and returned as\n`findings`. The previous file is kept as a backup and comes back when\nPHP-FPM does not run afterwards (`500 E_RESTART`).", "summary": "Replace the php.ini of a PHP version", "tags": [ "Server" ], "parameters": [ { "name": "php", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "sapi", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplacePhpIniRequest" } } } }, "responses": { "200": { "description": "`PhpIni`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PhpIni" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "patch": { "operationId": "updatePhpIniValues", "description": "Directives of the php.ini form are changed in place (or added to the\n`[PHP]` section) and the result is validated and saved as for\n`replacePhpIni`.", "summary": "Change directives of the php.ini of a PHP version", "tags": [ "Server" ], "parameters": [ { "name": "php", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "sapi", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePhpIniValuesRequest" } } } }, "responses": { "200": { "description": "`PhpIni`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PhpIni" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/system/php/versions/{php}/ini/{sapi}/backups": { "get": { "operationId": "listPhpIniBackups", "description": "The ten newest earlier versions of the file, newest first.", "summary": "List the php.ini backups", "tags": [ "Server" ], "parameters": [ { "name": "php", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "sapi", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size, from 1 to 1000. Without it the list is complete.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "offset", "in": "query", "description": "Items to skip. Used when `limit` is set; 0 when omitted.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Array of `PhpIniBackup`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PhpIniBackup" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/system/php/versions/{php}/ini/{sapi}/backups/{backup}/restore": { "post": { "operationId": "restorePhpIniBackup", "description": "The backup is validated and saved as for `replacePhpIni`; the current\nfile becomes a backup itself.", "summary": "Restore a php.ini backup", "tags": [ "Server" ], "parameters": [ { "name": "php", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "sapi", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "backup", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "`PhpIni`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PhpIni" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/system/ports": { "get": { "operationId": "getPortRegistry", "description": "The server range, the firewall, every account with its totals, every\nentry, the reserved ports, the sockets that listen in the range and the\nreconciliation findings.", "summary": "Get the port registry", "tags": [ "Server" ], "responses": { "200": { "description": "`PortRegistry`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PortRegistry" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/system/ports/adopt": { "post": { "operationId": "adoptPortRule", "description": "For an `unmanaged-rule` finding: the assigned single port becomes\npublic through that rule. Answers the port.", "summary": "Link a firewall rule to its port", "tags": [ "Server" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdoptPortRuleRequest" } } } }, "responses": { "200": { "description": "`PortEntry`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PortEntry" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "parameters": [ { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ] } }, "/system/ports/allocate": { "post": { "operationId": "allocatePorts", "description": "A `range` of the server range, or `count` ports as one block (from the\nreseller's pool for a customer of a reseller). Answers the user's ports.", "summary": "Allocate ports to a user", "tags": [ "Server" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllocatePortsRequest" } } } }, "responses": { "200": { "description": "The ports of the account with the totals of its pool; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PortEntry" } }, "meta": { "$ref": "#/components/schemas/PortListMeta" } }, "required": [ "data", "meta" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "parameters": [ { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ] } }, "/system/ports/close-rule": { "post": { "operationId": "closePortRule", "description": "For a `stale-rule` finding: deletes the rule that opens no public port.", "summary": "Delete a firewall rule", "tags": [ "Server" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClosePortRuleRequest" } } } }, "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "204": { "description": "No content.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "parameters": [ { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ] } }, "/system/ports/range": { "put": { "operationId": "setPortRange", "summary": "Change the server port range", "tags": [ "Server" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetPortRangeRequest" } } } }, "responses": { "200": { "description": "`PortRegistry`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PortRegistry" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "parameters": [ { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ] } }, "/system/ports/register": { "post": { "operationId": "registerPort", "description": "For an `orphan-socket` finding: allocates the port to `user` and\nreserves it there. Answers the user's ports.", "summary": "Register a listening port to its account", "tags": [ "Server" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterPortRequest" } } } }, "responses": { "200": { "description": "The ports of the account with the totals of its pool; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PortEntry" } }, "meta": { "$ref": "#/components/schemas/PortListMeta" } }, "required": [ "data", "meta" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "parameters": [ { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ] } }, "/system/ports/repair": { "post": { "operationId": "repairPorts", "description": "Runs `v-check-sys-ports repair` and answers the findings that are left.", "summary": "Repair the registry", "tags": [ "Server" ], "responses": { "200": { "description": "The findings left after the repair; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PortFinding" } } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "parameters": [ { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ] } }, "/system/ports/reserved": { "post": { "operationId": "addReservedPorts", "description": "Keeps a port or a range out of every allocation.", "summary": "Reserve ports of the server", "tags": [ "Server" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddReservedPortsRequest" } } } }, "responses": { "200": { "description": "`PortRegistry`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PortRegistry" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "parameters": [ { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ] } }, "/system/ports/reserved/{range}": { "delete": { "operationId": "deleteReservedPorts", "description": "Reservations of the panel's own services (`kind` `system`) stay.", "summary": "Delete a reservation", "tags": [ "Server" ], "parameters": [ { "name": "range", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{1,5}(-\\d{1,5})?$" }, "description": "A port (`30005`) or a range (`30010-30019`)." }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "204": { "description": "No content.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/system/restart": { "post": { "operationId": "restartServer", "description": "Reboots the whole server. `confirm_hostname` must be the server's host\nname (`meta.hostname` of listServices), otherwise `422`. Answers `204`\nonce the command accepted the restart; the server then goes down, so\nthere is no task to follow. Try it with `dry_run` first.", "summary": "Restart the server", "tags": [ "Server" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestartServerRequest" } } } }, "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "204": { "description": "No content.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "parameters": [ { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ] } }, "/system/services": { "get": { "operationId": "listServices", "description": "Every service the panel watches, with its state and usage. `meta`\ndescribes the server: host name, operating system, versions, uptime\nand load. The list is not paginated.", "summary": "List the services of the server", "tags": [ "Server" ], "responses": { "200": { "description": "Array of `Service`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Service" } }, "meta": { "$ref": "#/components/schemas/ServiceListMeta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/system/services/status/{kind}": { "get": { "operationId": "getServiceStatus", "description": "The plain text of one report of the services page: `cpu`, `mem`,\n`disk`, `net`, `web`, `dns`, `mail` or `db`.", "summary": "Get a status report of the server", "tags": [ "Server" ], "parameters": [ { "name": "kind", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`ServiceStatus`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ServiceStatus" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/system/services/{service}/logs": { "get": { "operationId": "getServiceLogs", "description": "The last `lines` lines (default 100, at most 500) of the systemd\njournal of a service that listServices shows, the newest last, for\ndiagnosis (E43 B5). A service the server does not list answers 404.\nThe lines may contain addresses and paths: a client that shows them to\nothers redacts them.", "summary": "Read the last lines of a service's journal", "tags": [ "Server" ], "parameters": [ { "name": "service", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "lines", "in": "query", "description": "Number of lines to return (1–500). Defaults to 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } } ], "responses": { "200": { "description": "`ServiceLog`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ServiceLog" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/system/services/{service}/restart": { "post": { "operationId": "restartService", "description": "Restarting `arcpanel` restarts the panel that answers this request.", "summary": "Restart a service", "tags": [ "Server" ], "parameters": [ { "name": "service", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "`Service`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Service" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/system/services/{service}/start": { "post": { "operationId": "startService", "summary": "Start a service", "tags": [ "Server" ], "parameters": [ { "name": "service", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "`Service`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Service" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/system/services/{service}/stop": { "post": { "operationId": "stopService", "description": "The panel's own service (`arcpanel`) is never stopped: `403`.", "summary": "Stop a service", "tags": [ "Server" ], "parameters": [ { "name": "service", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "`Service`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Service" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/system/settings": { "get": { "operationId": "getServerSettings", "description": "The allow-listed fields of every tab, grouped by tab. Tabs whose\nsystem the server does not run (`dns`, `mail`, `databases`) are left\nout. Secrets (the SMTP relay password, the remote backup password,\nthe restic repository, the panel's private key) answer `{\"set\": bool}`.", "summary": "Get the server settings", "tags": [ "Server" ], "responses": { "200": { "description": "The allow-listed fields of each tab the server has.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ServerSettings" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/system/settings/databases/hosts/{type}/{host}/password": { "put": { "operationId": "setDatabaseHostPassword", "description": "The password of `user` on a MySQL host of the server (getServerSettings\n`databases.hosts`). The password reaches the command in a file and is\nnever answered, also not in a dry run.", "summary": "Change the password of a database host", "tags": [ "Server" ], "parameters": [ { "name": "type", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "host", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetDatabaseHostPasswordRequest" } } } }, "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "204": { "description": "No content.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/system/settings/plugins/{plugin}": { "put": { "operationId": "setPlugin", "description": "`filemanager`, `web-terminal`, `cgroups`, `quota` or `firewall`, as\nthe system task (`202` with `sys:ID`). A plugin already in that state\nanswers `200`.", "summary": "Install or remove a plugin", "tags": [ "Server" ], "parameters": [ { "name": "plugin", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetPluginRequest" } } } }, "responses": { "200": { "description": "`Plugin`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Plugin" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "202": { "description": "`Task`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Task" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" }, "Link": { "$ref": "#/components/headers/Link" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/system/settings/web/php": { "put": { "operationId": "setPhpVersions", "description": "`versions` is the full list of PHP versions the server should have:\nmissing ones are installed, installed ones left out are removed, as\nthe system task (`202` with `sys:ID`). The default version and\nversions that web domains use are never removed: leaving them out\nanswers `422`. Without a change, the versions answer `200`.", "summary": "Set the PHP versions", "tags": [ "Server" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetPhpVersionsRequest" } } } }, "responses": { "200": { "description": "Array of `PhpVersion`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PhpVersion" } } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "202": { "description": "`Task`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Task" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" }, "Link": { "$ref": "#/components/headers/Link" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "parameters": [ { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ] } }, "/system/settings/{tab}": { "patch": { "operationId": "updateServerSettings", "description": "The fields of one tab (`general`, `web`, `mail`, `databases`,\n`backups`, `ssl`, `security`, `plugins`, `white-label`; `dns` is\nread-only), under the names of getServerSettings. Fields left out keep\ntheir value and only a changed value runs its command. A tab whose\nsystem the server does not run answers `404`. `API_SYSTEM`, `API`,\n`API_ALLOWED_IP`, `POLICY_SYSTEM_PROTECTED_ADMIN`,\n`POLICY_SYSTEM_HIDE_ADMIN`, `POLICY_SYSTEM_HIDE_SERVICES`, `pma_sso`,\n`pma_restrict` and the logo answer `403` naming the field; they stay\non the page. Secrets (`relay_password`, `password`, `repo`, `key`) are\naccepted and never answered. Answers the tab as getServerSettings\nshows it; a change that fails half-way names the steps applied.", "summary": "Change the settings of a tab", "tags": [ "Server" ], "parameters": [ { "name": "tab", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateServerSettingsRequest" } } } }, "responses": { "200": { "description": "The tab as getServerSettings shows it; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/GeneralSettings" }, { "$ref": "#/components/schemas/WebSettings" }, { "$ref": "#/components/schemas/MailSettings" }, { "$ref": "#/components/schemas/DatabasesSettings" }, { "$ref": "#/components/schemas/BackupsSettings" }, { "$ref": "#/components/schemas/SslSettings" }, { "$ref": "#/components/schemas/SecuritySettings" }, { "$ref": "#/components/schemas/PluginsSettings" }, { "$ref": "#/components/schemas/WhiteLabelSettings" } ] } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/system/tasks": { "get": { "operationId": "listSystemTasks", "description": "The current system task and Docker engine task.", "summary": "List the system tasks", "tags": [ "Tasks" ], "responses": { "200": { "description": "Array of `Task`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Task" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/system/updates": { "get": { "operationId": "listUpdates", "description": "The packages of the panel with their version and whether an update\nis available. `meta` holds the update settings (setUpdateSettings).\nThe list is not paginated.", "summary": "List the panel packages", "tags": [ "Server" ], "responses": { "200": { "description": "Array of `PanelPackage`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PanelPackage" } }, "meta": { "$ref": "#/components/schemas/UpdateSettings" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "runUpdates", "description": "Updates `package`, or every package without it, as the system task;\nthe panel may restart while it runs. Another running system task\nanswers `409 E_INUSE` with `existing`.", "summary": "Update the panel packages", "tags": [ "Server" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunUpdatesRequest" } } } }, "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "202": { "description": "`Task`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Task" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" }, "Link": { "$ref": "#/components/headers/Link" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "parameters": [ { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ] } }, "/system/updates/settings": { "put": { "operationId": "setUpdateSettings", "description": "`auto_update`, `send_email` and `send_log`; fields left out keep their\nvalue, and only a changed value runs its command.", "summary": "Change the update settings", "tags": [ "Server" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetUpdateSettingsRequest" } } } }, "responses": { "200": { "description": "`UpdateSettings`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/UpdateSettings" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "parameters": [ { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ] } }, "/tasks/{id}": { "get": { "operationId": "getTask", "summary": "Show a task", "tags": [ "Tasks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "lines", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } } ], "responses": { "200": { "description": "`Task`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Task" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "410": { "$ref": "#/components/responses/Gone" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/users": { "get": { "operationId": "listUsers", "description": "Every user for an administrator, the customers for a reseller.", "summary": "List users", "tags": [ "Users" ], "parameters": [ { "name": "role", "in": "query", "description": "Only users of this role.", "schema": { "anyOf": [ { "$ref": "#/components/schemas/ApiRole" }, { "type": "null" } ] } }, { "name": "owner", "in": "query", "description": "Administrators: only the customers of this reseller (or of the administrator).", "schema": { "type": [ "string", "null" ], "pattern": "^[[:alnum:]][-.\\w]*$", "maxLength": 32 } }, { "name": "limit", "in": "query", "description": "Page size, from 1 to 1000. Without it the list is complete.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "offset", "in": "query", "description": "Items to skip. Used when `limit` is set; 0 when omitted.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Array of `User`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/User" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "createUser", "description": "An administrator creates any user (with `role`, `owner` and\n`login_disabled`), a reseller a customer of its own within its plan.\nA repeated call answers 409 `E_EXISTS`.", "summary": "Create a user", "tags": [ "Users" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreUserRequest" } } } }, "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "201": { "description": "`User`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/User" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" }, "Location": { "$ref": "#/components/headers/Location" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "parameters": [ { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ] } }, "/users/{user}": { "get": { "operationId": "getUser", "summary": "Get a user", "tags": [ "Users" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`User`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/User" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "operationId": "updateUser", "description": "The fields left out keep their value. Name, contact e-mail, language\nand `allowed_ips`: users for their own account, administrators and\nresellers for those they manage. `nameservers`: administrators and\nresellers for their customers, an administrator for itself.\n`login_disabled`: administrators, not for themselves. `role`,\n`owner`, `shell` and `php_cli`: administrators, never for the root\nadministrator; `role` and `owner` not for themselves either. A\nreseller with customers cannot be demoted, a user becomes a reseller\nonly with a package that allows customers. A field the caller may not\nchange answers 403 naming it, before anything runs.", "summary": "Update a user", "tags": [ "Users" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUserRequest" } } } }, "responses": { "200": { "description": "`User`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/User" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "delete": { "operationId": "deleteUser", "description": "Deletes the account with all its data. A reseller with customers\nanswers 409 `E_INUSE`.", "summary": "Delete a user", "tags": [ "Users" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "204": { "description": "No content.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/access-keys": { "get": { "operationId": "listAccessKeys", "description": "Oldest first, never with their secrets.", "summary": "List the access keys of a user", "tags": [ "Access keys" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size, from 1 to 1000. Without it the list is complete.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "offset", "in": "query", "description": "Items to skip. Used when `limit` is set; 0 when omitted.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Array of `AccessKey`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AccessKey" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "createAccessKey", "description": "`permissions` are sets of `GET /access-key-sets`: a key gives only\nsets it holds itself, and only sets the owner may have (sets of role\n`user`, every set for the root administrator). An empty list makes a\nkey that may run every command: only for an administrator's own\naccount, and only by a key without sets. The answer carries the\nsecret, once, with `Cache-Control: no-store`; no other answer, log or\ndry run shows it. `allowed_ips` and `expires_at` restrict the key for\nAPI v1 and v2 and cannot be changed later: a different restriction\nmeans a new key and the deletion of the old one.", "summary": "Create an access key", "tags": [ "Access keys" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAccessKeyRequest" } } } }, "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "201": { "description": "`NewAccessKey`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/NewAccessKey" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" }, "Location": { "$ref": "#/components/headers/Location" }, "Cache-Control": { "description": "`no-store`: the answer carries the secret of the new key, which no other answer shows (E34 batch 6 D62).", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/access-keys/{key}": { "get": { "operationId": "getAccessKey", "summary": "Get an access key", "tags": [ "Access keys" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`AccessKey`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AccessKey" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "deleteAccessKey", "description": "A key may always delete itself, whatever its permission sets: to\nrotate a key, create the new one, then delete the old one with it.\nDeleting another key needs a set that allows it.", "summary": "Delete an access key", "tags": [ "Access keys" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "204": { "description": "No content.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/app-process-presets": { "get": { "operationId": "getAppProcessPresets", "description": "With `domain`, each preset says whether its files were found in `cwd`\nof that domain and why its runtime is missing.", "summary": "List the presets of app processes", "tags": [ "App processes" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^[^\\s\\/]+$", "maxLength": 253 } }, { "name": "cwd", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^(\\.|[A-Za-z0-9_][A-Za-z0-9._\\/@+-]{0,199})$" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": {} } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/users/{user}/app-process-task": { "get": { "operationId": "getAppProcessTask", "summary": "Get the last one-off task of a user's app processes", "tags": [ "App processes" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "domain": { "type": "string" }, "name": { "type": "string" }, "task": { "type": "string" }, "status": { "type": "string" }, "exit_code": { "type": [ "integer", "null" ] }, "started_at": { "type": [ "string", "null" ] }, "finished_at": { "type": [ "string", "null" ] } }, "required": [ "id", "domain", "name", "task", "status", "exit_code", "started_at", "finished_at" ] } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/users/{user}/app-processes": { "get": { "operationId": "listAppProcesses", "summary": "List the app processes of a user", "tags": [ "App processes" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Array of `AppProcess`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AppProcess" } }, "meta": { "$ref": "#/components/schemas/AppProcessListMeta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "createAppProcess", "summary": "Create an app process", "tags": [ "App processes" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreAppProcessRequest" } } } }, "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "201": { "description": "`AppProcess`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AppProcess" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" }, "Location": { "$ref": "#/components/headers/Location" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/app-processes/{domain}/{name}": { "get": { "operationId": "getAppProcess", "summary": "Get an app process", "tags": [ "App processes" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`AppProcess`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AppProcess" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "operationId": "updateAppProcess", "description": "Changes the command (with `cwd`) and the limits (`memory_mb` with\n`cpus`); a running process is restarted.", "summary": "Update an app process", "tags": [ "App processes" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAppProcessRequest" } } } }, "responses": { "200": { "description": "`AppProcess`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AppProcess" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "delete": { "operationId": "deleteAppProcess", "summary": "Delete an app process", "tags": [ "App processes" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "204": { "description": "No content.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/app-processes/{domain}/{name}/env": { "get": { "operationId": "getAppProcessEnv", "summary": "List the environment of an app process", "tags": [ "App processes" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "reveal", "in": "query", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Environment names and set flags; values only with `reveal=1`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/NodeAppEnvEntry" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "setAppProcessEnv", "description": "An entry without `value` keeps its stored value. Values may reference\nsecrets as `{{secret:NAME}}`; a running process is restarted.", "summary": "Replace the environment of an app process", "tags": [ "App processes" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetAppProcessEnvRequest" } } } }, "responses": { "200": { "description": "The saved environment (names and set flags; values only when the key may reveal them); with `dry_run`, the planned steps.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/NodeAppEnvEntry" } } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/app-processes/{domain}/{name}/logs": { "get": { "operationId": "getAppProcessLogs", "description": "`stream` is `process` (the output of the process and its reloads) or\n`task` (the last one-off task of the domain's processes).", "summary": "Read a snapshot of an app process log", "tags": [ "App processes" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "lines", "in": "query", "description": "Number of lines to return (1–1000). Defaults to 200.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 200 } }, { "name": "after", "in": "query", "description": "Opaque cursor from `meta.next` of a previous snapshot; returns lines that appeared since.", "schema": { "type": "string", "maxLength": 64 } }, { "name": "stream", "in": "query", "description": "`process` (the output of the process and its reloads) or `task` (the last one-off task).", "schema": { "type": "string", "enum": [ "process", "task" ], "default": "process" } } ], "responses": { "200": { "description": "Log lines and a cursor for the next snapshot.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "lines": { "type": "array", "items": {} } }, "required": [ "lines" ] }, "meta": { "$ref": "#/components/schemas/AppProcessLogMeta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/users/{user}/app-processes/{domain}/{name}/reload": { "post": { "operationId": "reloadAppProcess", "description": "Runs the reload action of the preset: a command such as\n`php artisan octane:reload`, a signal, or a restart.", "summary": "Reload an app process", "tags": [ "App processes" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "`AppProcess`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AppProcess" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/app-processes/{domain}/{name}/restart": { "post": { "operationId": "restartAppProcess", "summary": "Restart an app process", "tags": [ "App processes" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "`AppProcess`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AppProcess" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/app-processes/{domain}/{name}/start": { "post": { "operationId": "startAppProcess", "summary": "Start an app process", "tags": [ "App processes" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "`AppProcess`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AppProcess" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/app-processes/{domain}/{name}/stop": { "post": { "operationId": "stopAppProcess", "summary": "Stop an app process", "tags": [ "App processes" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "`AppProcess`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AppProcess" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/app-processes/{domain}/{name}/tasks": { "post": { "operationId": "startAppProcessTask", "description": "Runs `composer-install`, `migrate`, `pip-install`, `bundle-install` or a\n`custom` command as the user in the working directory of the process.\nOne task runs at a time per user; follow it with\n`getAppProcessTask` and the `task` log stream.", "summary": "Start a one-off task of an app process", "tags": [ "App processes" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartAppProcessTaskRequest" } } } }, "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "202": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "domain": { "type": "string" }, "name": { "type": "string" }, "task": { "type": "string" }, "status": { "type": "string" }, "exit_code": { "type": [ "integer", "null" ] }, "started_at": { "type": [ "string", "null" ] }, "finished_at": { "type": [ "string", "null" ] } }, "required": [ "id", "domain", "name", "task", "status", "exit_code", "started_at", "finished_at" ] } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" }, "Location": { "$ref": "#/components/headers/Location" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/auth-logs": { "get": { "operationId": "listUserAuthLogs", "description": "Newest first, paged like the action log. Not available in demo mode.", "summary": "List the login history of a user", "tags": [ "Logs" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Entries to return, from 1 to 1000. Defaults to 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } }, { "name": "offset", "in": "query", "description": "Newer entries to skip, from 0 to 8999.", "schema": { "type": "integer", "minimum": 0, "maximum": 8999, "default": 0 } } ], "responses": { "200": { "description": "Array of `AuthLogEntry`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AuthLogEntry" } }, "meta": { "$ref": "#/components/schemas/LogListMeta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "clearUserAuthLogs", "summary": "Clear the login history of a user", "tags": [ "Logs" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "204": { "description": "No content.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/backup-exclusions": { "put": { "operationId": "setBackupExclusions", "description": "Send the full object. A type left out of the body keeps its current list.", "summary": "Set backup exclusions of a user", "tags": [ "Backups" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetBackupExclusionsRequest" } } } }, "responses": { "200": { "description": "`BackupExclusions`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BackupExclusions" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "get": { "operationId": "getBackupExclusions", "summary": "Get backup exclusions of a user", "tags": [ "Backups" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`BackupExclusions`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BackupExclusions" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/users/{user}/backups": { "get": { "operationId": "listBackups", "description": "Newest first. `meta.limit` is the number of archives kept; `meta.incremental`\nis whether the package has incremental backups.", "summary": "List the backup archives of a user", "tags": [ "Backups" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size, from 1 to 1000. Without it the list is complete.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "offset", "in": "query", "description": "Items to skip. Used when `limit` is set; 0 when omitted.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Array of `Backup`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Backup" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "createBackup", "description": "Queues a backup of the user. When a backup or restore is already queued,\nanswers 409 `E_EXISTS` with `existing` set to that task.", "summary": "Create a backup", "tags": [ "Backups" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "202": { "description": "`Task`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Task" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" }, "Location": { "$ref": "#/components/headers/Location" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/backups/{backup}": { "get": { "operationId": "getBackup", "summary": "Get a backup archive", "tags": [ "Backups" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "backup", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`Backup`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Backup" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "deleteBackup", "summary": "Delete a backup archive", "tags": [ "Backups" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "backup", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "204": { "description": "No content.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/backups/{backup}/download": { "get": { "operationId": "downloadBackup", "description": "Serves a local archive through nginx. A remote archive is fetched first\nand answers 202 with the queue task.", "summary": "Download a backup archive", "tags": [ "Backups" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "backup", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The archive when it is on this server: an empty body with `X-Accel-Redirect` so nginx serves the bytes (D35).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" }, "Content-Type": { "description": "Usually `application/octet-stream` or `application/x-gzip`.", "schema": { "type": "string" } }, "Content-Disposition": { "description": "`attachment; filename=\"\"`", "schema": { "type": "string" } }, "X-Accel-Redirect": { "description": "Internal nginx path to the archive file (D35).", "schema": { "type": "string" } } }, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "202": { "description": "The fetch task when the archive is only on a remote backup host.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Task" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" }, "Location": { "$ref": "#/components/headers/Location" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/users/{user}/backups/{backup}/restore": { "post": { "operationId": "restoreBackup", "description": "Optional `web`, `dns`, `mail`, `db` and `udir` lists and a `cron` flag\nrestore only those objects. An empty body restores everything.", "summary": "Restore a backup archive", "tags": [ "Backups" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "backup", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestoreBackupRequest" } } } }, "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "202": { "description": "`Task`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Task" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" }, "Location": { "$ref": "#/components/headers/Location" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/cron-jobs": { "get": { "operationId": "listCronJobs", "description": "`meta.timezone` is the server's time zone.", "summary": "List the cron jobs of a user", "tags": [ "Cron" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size, from 1 to 1000. Without it the list is complete.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "offset", "in": "query", "description": "Items to skip. Used when `limit` is set; 0 when omitted.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Array of `CronJob`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CronJob" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "createCronJob", "description": "The id is the next one after the highest the user has. A job with the\nsame schedule and command answers 409 `E_EXISTS` with `existing`.", "summary": "Create a cron job", "tags": [ "Cron" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreCronJobRequest" } } } }, "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "201": { "description": "`CronJob`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CronJob" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" }, "Location": { "$ref": "#/components/headers/Location" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/cron-jobs/{id}": { "get": { "operationId": "getCronJob", "summary": "Get a cron job", "tags": [ "Cron" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`CronJob`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CronJob" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "operationId": "updateCronJob", "description": "The id does not change. Fields left out keep their value.", "summary": "Update a cron job", "tags": [ "Cron" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCronJobRequest" } } } }, "responses": { "200": { "description": "`CronJob`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CronJob" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "delete": { "operationId": "deleteCronJob", "summary": "Delete a cron job", "tags": [ "Cron" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "204": { "description": "No content.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/cron-jobs/{id}/suspend": { "post": { "operationId": "suspendCronJob", "summary": "Suspend a cron job", "tags": [ "Cron" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "`CronJob`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CronJob" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/cron-jobs/{id}/unsuspend": { "post": { "operationId": "unsuspendCronJob", "summary": "Unsuspend a cron job", "tags": [ "Cron" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "`CronJob`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CronJob" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/cron-reports": { "get": { "operationId": "getCronReports", "summary": "Whether cron mails the output of the user's jobs", "tags": [ "Cron" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ] } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "setCronReports", "description": "Nothing runs when the value is unchanged.", "summary": "Turn cron reports on or off", "tags": [ "Cron" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetCronReportsRequest" } } } }, "responses": { "200": { "description": "; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ] } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/databases": { "get": { "operationId": "listDatabases", "summary": "List the databases of a user", "tags": [ "Databases" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size, from 1 to 1000. Without it the list is complete.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "offset", "in": "query", "description": "Items to skip. Used when `limit` is set; 0 when omitted.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Array of `Database`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Database" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "createDatabase", "description": "`name` and `db_user` are the short names. The stored name adds the owner\nprefix. A full name the user has answers 409 `E_EXISTS`.", "summary": "Create a database", "tags": [ "Databases" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreDatabaseRequest" } } } }, "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "201": { "description": "`Database`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Database" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" }, "Location": { "$ref": "#/components/headers/Location" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/databases/{database}": { "get": { "operationId": "getDatabase", "summary": "Get a database", "tags": [ "Databases" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "database", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`Database`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Database" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "operationId": "updateDatabase", "description": "`db_user` is the short name.", "summary": "Change the database user", "tags": [ "Databases" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "database", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDatabaseRequest" } } } }, "responses": { "200": { "description": "`Database`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Database" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "delete": { "operationId": "deleteDatabase", "summary": "Delete a database", "tags": [ "Databases" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "database", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "204": { "description": "No content.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/databases/{database}/dump": { "post": { "operationId": "dumpDatabase", "description": "Runs `v-dump-database` and serves the `.sql.gz` through nginx (D35).\nThe dump file is removed about an hour later, as on the Databases page.", "summary": "Export a database dump", "tags": [ "Databases" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "database", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "The gzip dump: an empty body with `X-Accel-Redirect` so nginx serves the bytes (D35).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" }, "Content-Type": { "description": "`application/gzip`.", "schema": { "type": "string" } }, "Content-Disposition": { "description": "`attachment; filename=\".sql.gz\"`", "schema": { "type": "string" } }, "X-Accel-Redirect": { "description": "Internal nginx path under `/backup/` (D35).", "schema": { "type": "string" } } }, "content": { "application/gzip": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/databases/{database}/password": { "put": { "operationId": "changeDatabasePassword", "summary": "Change the password of a database", "tags": [ "Databases" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "database", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeDatabasePasswordRequest" } } } }, "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "204": { "description": "No content.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/databases/{database}/rebuild": { "post": { "operationId": "rebuildDatabase", "description": "Administrators only.", "summary": "Rebuild a database", "tags": [ "Databases" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "database", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "`Database`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Database" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/databases/{database}/suspend": { "post": { "operationId": "suspendDatabase", "summary": "Suspend a database", "tags": [ "Databases" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "database", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "`Database`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Database" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/databases/{database}/unsuspend": { "post": { "operationId": "unsuspendDatabase", "summary": "Unsuspend a database", "tags": [ "Databases" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "database", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "`Database`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Database" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/dns-zones": { "get": { "operationId": "listDnsZones", "summary": "List the DNS zones of a user", "tags": [ "DNS" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size, from 1 to 1000. Without it the list is complete.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "offset", "in": "query", "description": "Items to skip. Used when `limit` is set; 0 when omitted.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Array of `DnsZone`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DnsZone" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "createDnsZone", "description": "TTL 14400 and an expiry one year ahead when left out; only values that\ndiffer add a step. A zone the user has answers 409 `E_EXISTS`.", "summary": "Create a DNS zone", "tags": [ "DNS" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreDnsZoneRequest" } } } }, "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "201": { "description": "`DnsZone`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DnsZone" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" }, "Location": { "$ref": "#/components/headers/Location" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/dns-zones/{domain}": { "get": { "operationId": "getDnsZone", "summary": "Get a DNS zone", "tags": [ "DNS" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`DnsZone`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DnsZone" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "operationId": "updateDnsZone", "description": "The IP address, template, TTL, SOA, expiry and DNSSEC. Fields left out\nkeep their value.", "summary": "Update a DNS zone", "tags": [ "DNS" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDnsZoneRequest" } } } }, "responses": { "200": { "description": "`DnsZone`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DnsZone" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "delete": { "operationId": "deleteDnsZone", "summary": "Delete a DNS zone", "tags": [ "DNS" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "204": { "description": "No content.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/dns-zones/{domain}/dnssec": { "get": { "operationId": "getDnsZoneDnssec", "description": "404 when the zone has no DNSSEC.", "summary": "Get the DNSSEC public key of a zone", "tags": [ "DNS" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`DnsZoneDnssec`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DnsZoneDnssec" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/users/{user}/dns-zones/{domain}/rebuild": { "post": { "operationId": "rebuildDnsZone", "description": "Administrators only.", "summary": "Rebuild a DNS zone", "tags": [ "DNS" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "`DnsZone`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DnsZone" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/dns-zones/{domain}/records": { "get": { "operationId": "listDnsRecords", "description": "`name` and `type` match exactly.", "summary": "List the records of a DNS zone", "tags": [ "DNS" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "query", "description": "Exact record name.", "schema": { "type": "string", "maxLength": 253 } }, { "name": "type", "in": "query", "description": "Exact record type.", "schema": { "type": "string", "enum": [ "A", "AAAA", "CAA", "CNAME", "DNSKEY", "DS", "IPSECKEY", "KEY", "MX", "NS", "PTR", "SPF", "SRV", "TLSA", "TXT" ] } }, { "name": "limit", "in": "query", "description": "Page size, from 1 to 1000. Without it the list is complete.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "offset", "in": "query", "description": "Items to skip. Used when `limit` is set; 0 when omitted.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Array of `DnsRecord`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DnsRecord" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "createDnsRecord", "description": "The id is the next one after the highest the zone has. A record with\nthe same name, type, value and priority answers 409 `E_EXISTS` with\n`existing`.", "summary": "Create a DNS record", "tags": [ "DNS" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreDnsRecordRequest" } } } }, "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "201": { "description": "`DnsRecord`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DnsRecord" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" }, "Location": { "$ref": "#/components/headers/Location" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/dns-zones/{domain}/records/{id}": { "get": { "operationId": "getDnsRecord", "summary": "Get a DNS record", "tags": [ "DNS" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`DnsRecord`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DnsRecord" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "operationId": "updateDnsRecord", "description": "The id does not change.", "summary": "Update a DNS record", "tags": [ "DNS" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDnsRecordRequest" } } } }, "responses": { "200": { "description": "`DnsRecord`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DnsRecord" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "delete": { "operationId": "deleteDnsRecord", "summary": "Delete a DNS record", "tags": [ "DNS" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "204": { "description": "No content.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/dns-zones/{domain}/records/{id}/suspend": { "post": { "operationId": "suspendDnsRecord", "summary": "Suspend a DNS record", "tags": [ "DNS" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "`DnsRecord`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DnsRecord" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/dns-zones/{domain}/records/{id}/unsuspend": { "post": { "operationId": "unsuspendDnsRecord", "summary": "Unsuspend a DNS record", "tags": [ "DNS" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "`DnsRecord`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DnsRecord" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/dns-zones/{domain}/suspend": { "post": { "operationId": "suspendDnsZone", "description": "A suspended zone answers as it is.", "summary": "Suspend a DNS zone", "tags": [ "DNS" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "`DnsZone`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DnsZone" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/dns-zones/{domain}/unsuspend": { "post": { "operationId": "unsuspendDnsZone", "summary": "Unsuspend a DNS zone", "tags": [ "DNS" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "`DnsZone`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DnsZone" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/docker-apps": { "get": { "operationId": "listDockerApps", "summary": "List the Docker apps of a user", "tags": [ "Docker apps" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Array of `DockerApp`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DockerApp" } }, "meta": { "$ref": "#/components/schemas/DockerAppListMeta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "createDockerApp", "summary": "Install a Docker app", "tags": [ "Docker apps" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreDockerAppRequest" } } } }, "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "202": { "description": "`Task`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Task" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" }, "Location": { "$ref": "#/components/headers/Location" }, "Link": { "$ref": "#/components/headers/Link" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/docker-apps/{name}": { "get": { "operationId": "getDockerApp", "summary": "Get a Docker app", "tags": [ "Docker apps" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`DockerApp`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DockerApp" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "deleteDockerApp", "summary": "Delete a Docker app", "tags": [ "Docker apps" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "keep_data", "in": "query", "schema": { "type": "boolean", "default": false } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "204": { "description": "No content.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/docker-apps/{name}/domain": { "put": { "operationId": "setDockerAppDomain", "summary": "Change the domain of a Docker app", "tags": [ "Docker apps" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetDockerAppDomainRequest" } } } }, "responses": { "200": { "description": "`DockerApp`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DockerApp" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/docker-apps/{name}/env": { "get": { "operationId": "getDockerAppEnv", "summary": "List the environment of a Docker app", "tags": [ "Docker apps" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Environment variables with secrets masked (D42).", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DockerAppEnvEntry" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "setDockerAppEnv", "summary": "Replace the environment of a Docker app", "tags": [ "Docker apps" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetDockerAppEnvRequest" } } } }, "responses": { "200": { "description": "The saved environment (D42); with `dry_run`, the planned steps.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DockerAppEnvEntry" } } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/docker-apps/{name}/limits": { "put": { "operationId": "setDockerAppLimits", "summary": "Change the resource limits of a Docker app", "tags": [ "Docker apps" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetDockerAppLimitsRequest" } } } }, "responses": { "200": { "description": "`DockerApp`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DockerApp" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/docker-apps/{name}/logs": { "get": { "operationId": "getDockerAppLogs", "summary": "Read a snapshot of Docker app logs", "tags": [ "Docker apps" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "lines", "in": "query", "description": "Number of lines to return (1–1000). Defaults to 200.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 200 } }, { "name": "after", "in": "query", "description": "Opaque cursor from `meta.next` of a previous snapshot; returns lines that appeared since.", "schema": { "type": "string", "maxLength": 128 } }, { "name": "service", "in": "query", "description": "Compose service to read (`all` for every service).", "schema": { "type": "string", "default": "all" } } ], "responses": { "200": { "description": "Log lines and a cursor for the next snapshot (D43).", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "lines": { "type": "array", "items": { "type": "object", "properties": { "time": { "type": "string" }, "service": { "type": "string" }, "text": { "type": "string" } }, "required": [ "time", "service", "text" ] } } }, "required": [ "lines" ] }, "meta": { "$ref": "#/components/schemas/DockerAppLogMeta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/users/{user}/docker-apps/{name}/restart": { "post": { "operationId": "restartDockerApp", "summary": "Restart a Docker app", "tags": [ "Docker apps" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "`DockerApp`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DockerApp" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/docker-apps/{name}/start": { "post": { "operationId": "startDockerApp", "summary": "Start a Docker app", "tags": [ "Docker apps" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "`DockerApp`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DockerApp" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/docker-apps/{name}/stop": { "post": { "operationId": "stopDockerApp", "summary": "Stop a Docker app", "tags": [ "Docker apps" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "`DockerApp`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DockerApp" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/docker-apps/{name}/tasks": { "post": { "operationId": "startDockerAppTask", "summary": "Start a long-running Docker app task", "tags": [ "Docker apps" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartDockerAppTaskRequest" } } } }, "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "202": { "description": "`Task`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Task" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" }, "Link": { "$ref": "#/components/headers/Link" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/files": { "get": { "operationId": "listFiles", "description": "The entries of a folder of the user's home directory: folders first,\nthen by `sort` and `order`. `mime` and `writable` are null in a list\n(getFileInfo reads them). Without `limit` the list is complete.", "summary": "List a folder", "tags": [ "Files" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "query", "description": "Folder relative to the home directory; the home directory when left out.", "schema": { "type": [ "string", "null" ] } }, { "name": "sort", "in": "query", "description": "Folders come first, then this order.", "schema": { "type": "string", "enum": [ "name", "size", "mtime" ] } }, { "name": "order", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "hidden", "in": "query", "description": "List names that start with a dot (default true).", "schema": { "type": "boolean", "default": true } }, { "name": "limit", "in": "query", "description": "Page size, from 1 to 1000. Without it the list is complete.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "offset", "in": "query", "description": "Items to skip. Used when `limit` is set; 0 when omitted.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Array of `FileEntry`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FileEntry" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/users/{user}/files/chmod": { "post": { "operationId": "changeFileMode", "description": "Sets the octal `mode` of `paths`. A folder changes alone, or with\n`recursive` everything inside it too: folders get `mode` and files\n`files_mode` (default `mode`); symbolic links are skipped. The change\nstops at the first failure: `error.path` names it and `error.done`\nlists the paths changed before. A change longer than 600 seconds\nanswers `504` from the web server and may leave part of the work\ndone.", "summary": "Change permissions", "tags": [ "Files" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeFileModeRequest" } } } }, "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "204": { "description": "No content.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/files/compress": { "post": { "operationId": "compressFiles", "description": "Zips `paths`, entries of one folder, into the new archive `name` in\nthat folder; an archive that exists answers `409` `E_EXISTS` with\n`conflicts`. Symbolic links are stored as links. Answers the\narchive's entry. Compressing longer than 600 seconds answers `504`\nfrom the web server and may leave the archive behind.", "summary": "Compress into a zip archive", "tags": [ "Files" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompressFilesRequest" } } } }, "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "201": { "description": "`FileEntry`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FileEntry" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" }, "Location": { "$ref": "#/components/headers/Location" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/files/content": { "get": { "operationId": "readFile", "description": "The content of a regular file of at most 2 MiB (`413` `E_LIMIT`\nabove) with its SHA-256 `hash`, which saveFile expects back. Bytes\nthat are not UTF-8 are replaced and `utf8` is false: saving such\ncontent back would change the file.", "summary": "Read a text file", "tags": [ "Files" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "query", "required": true, "description": "File relative to the home directory.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`FileContent`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FileContent" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/TooLarge" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "saveFile", "description": "Writes `content` over the file at `path`, or creates it when `hash`\nis null. `hash` is the hash of the version read: when the file\nchanged since, nothing is written and the answer is `409` `E_INUSE`;\nan existing file with a null `hash` answers `409` `E_EXISTS`. The\nfile keeps its mode, owner and the line endings sent. Content above\n2 MiB answers `413` `E_LIMIT`, a full disk quota `422` `E_LIMIT`, too\nlittle space in the panel's staging folder `507` `E_DISK`.", "summary": "Save a text file", "tags": [ "Files" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveFileRequest" } } } }, "responses": { "200": { "description": "`FileContent`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FileContent" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/TooLarge" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" }, "507": { "$ref": "#/components/responses/InsufficientStorage" } } } }, "/users/{user}/files/copy": { "post": { "operationId": "copyFiles", "description": "Copies `paths` into the folder `destination`. A name that exists\nthere stops the copy before anything changes, with `409` `E_EXISTS`\nand `conflicts`, unless `on_conflict` says otherwise; within its own\nfolder a copy always gets a free name. The copy stops at the first\nfailure: `error.path` names it and `error.done` lists the paths\ncopied before. A copy longer than 600 seconds answers `504` from the\nweb server and may leave part of the work done.", "summary": "Copy files and folders", "tags": [ "Files" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferFilesRequest" } } } }, "responses": { "200": { "description": "The folder and the names created in it; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "type": "object", "properties": { "destination": { "type": "string", "description": "the folder, relative to the home directory" }, "names": { "type": "array", "description": "the names created in the folder, in the order of `paths`; skipped entries are left out", "items": { "type": "string" } } }, "required": [ "destination", "names" ] } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/files/delete": { "post": { "operationId": "deleteFiles", "description": "Deletes `paths`, folders with their content; there is no trash. The\ndelete stops at the first failure: `error.path` names it and\n`error.done` lists the paths deleted before. A delete longer than 600\nseconds answers `504` from the web server and may leave part of the\nwork done.", "summary": "Delete files and folders", "tags": [ "Files" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteFilesRequest" } } } }, "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "204": { "description": "No content.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/files/directories": { "post": { "operationId": "createDirectory", "description": "A new folder `name` in the folder `path`; a name that exists answers\n`409` `E_EXISTS` with `conflicts`.", "summary": "Create a folder", "tags": [ "Files" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFileRequest" } } } }, "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "201": { "description": "`FileEntry`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FileEntry" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" }, "Location": { "$ref": "#/components/headers/Location" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/files/download": { "post": { "operationId": "downloadFiles", "description": "Answers the bytes in this request: one file as it is, a folder or\nseveral entries of one folder as a zip (symbolic links stored as\nlinks). The panel prepares the download with `v-add-fs-download` as\nthe user and arcpanel-nginx sends it (`X-Accel-Redirect`, with range\nrequests). `inline` shows one image, audio or video file, PDF or plain\ntext in the browser; SVG is always an attachment. Too little space in\nthe panel's staging folder answers `507` `E_DISK`. A zip that takes\nlonger than 600 seconds answers `504` from the web server.", "summary": "Download files", "tags": [ "Files" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DownloadFilesRequest" } } } }, "responses": { "200": { "description": "The file, or a zip of a folder or several entries: an empty body with `X-Accel-Redirect` so nginx serves the bytes (D51); with `dry_run`, the planned steps.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" }, "Content-Type": { "description": "The type of the file; `application/zip` for a zip.", "schema": { "type": "string" } }, "Content-Disposition": { "description": "`attachment`, or `inline` for a file shown in the browser, with an ASCII `filename` and the RFC 5987 `filename*`.", "schema": { "type": "string" } }, "Content-Security-Policy": { "description": "`default-src 'none'` with `sandbox` for anything but a PDF.", "schema": { "type": "string" } }, "X-Content-Type-Options": { "description": "`nosniff`.", "schema": { "type": "string" } }, "X-Accel-Redirect": { "description": "Internal nginx path `/_arc_files/` of the prepared download (D51).", "schema": { "type": "string" } } }, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } }, "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" }, "507": { "$ref": "#/components/responses/InsufficientStorage" } } } }, "/users/{user}/files/extract": { "post": { "operationId": "extractArchive", "description": "Unpacks the archive `path` (zip, tar.gz, tgz, tar.bz2, tbz, tar.zst\nor 7z) into `destination`, a folder that must not exist yet: the plan\ncreates it, so nothing is overwritten. An existing `destination`\nanswers `409` `E_EXISTS` with `conflicts`; single-file `.gz`, `.bz2`\nand `.zst` are refused. Answers the new folder's entry. Extracting\nlonger than 600 seconds answers `504` from the web server and may\nleave part of the content behind.", "summary": "Extract an archive", "tags": [ "Files" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractArchiveRequest" } } } }, "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "201": { "description": "`FileEntry`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FileEntry" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" }, "Location": { "$ref": "#/components/headers/Location" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/files/info": { "get": { "operationId": "getFileInfo", "description": "One entry with its MIME type and whether the user may write it.", "summary": "Get a file or folder", "tags": [ "Files" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "query", "description": "Path relative to the home directory; the home directory when left out.", "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "`FileEntry`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FileEntry" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/users/{user}/files/move": { "post": { "operationId": "moveFiles", "description": "Moves `paths` into the folder `destination`, with the conflict rules\nof copyFiles; an entry already in `destination` stays where it is.\nThe move stops at the first failure: `error.path` names it and\n`error.done` lists the paths moved before. A move longer than 600\nseconds answers `504` from the web server and may leave part of the\nwork done.", "summary": "Move files and folders", "tags": [ "Files" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferFilesRequest" } } } }, "responses": { "200": { "description": "The folder and the names created in it; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "type": "object", "properties": { "destination": { "type": "string", "description": "the folder, relative to the home directory" }, "names": { "type": "array", "description": "the names created in the folder, in the order of `paths`; skipped entries are left out", "items": { "type": "string" } } }, "required": [ "destination", "names" ] } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/files/rename": { "post": { "operationId": "renameFile", "description": "A new name in the same folder; a name that exists answers `409`\n`E_EXISTS` with `conflicts`. Answers the entry at its new path.", "summary": "Rename a file or folder", "tags": [ "Files" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenameFileRequest" } } } }, "responses": { "200": { "description": "`FileEntry`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FileEntry" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/files/search": { "get": { "operationId": "searchFiles", "description": "Entries whose name matches `q` in the folder `path` and below, at\nmost 500 (`meta.truncated` when there were more). A search that takes\nlonger than 10 seconds answers `422` `E_LIMIT`: narrow it.", "summary": "Search by name", "tags": [ "Files" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "query", "description": "Folder to search in, with its subfolders; the home directory when left out.", "schema": { "type": [ "string", "null" ] } }, { "name": "q", "in": "query", "required": true, "description": "A name or a shell pattern (`*`, `?`, `[…]`), 1 to 100 characters without `/`; a term without a pattern character matches as `*q*`.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } } ], "responses": { "200": { "description": "Array of `FileSearchResult`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FileSearchResult" } }, "meta": { "$ref": "#/components/schemas/FileSearchMeta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/users/{user}/files/size": { "get": { "operationId": "getFolderSize", "description": "The bytes used by a folder and everything in it (`du -sb` as the\nuser). Counting longer than 30 seconds answers `422` `E_LIMIT`.", "summary": "Get the size of a folder", "tags": [ "Files" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "query", "description": "Path relative to the home directory; the home directory when left out.", "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "The bytes of the folder and everything in it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "path": { "type": "string", "description": "path relative to the home directory" }, "size": { "type": "integer", "description": "bytes" } }, "required": [ "path", "size" ] } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/users/{user}/files/touch": { "post": { "operationId": "createFile", "description": "A new empty file `name` in the folder `path`; a name that exists\nanswers `409` `E_EXISTS` with `conflicts`.", "summary": "Create an empty file", "tags": [ "Files" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFileRequest" } } } }, "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "201": { "description": "`FileEntry`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FileEntry" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" }, "Location": { "$ref": "#/components/headers/Location" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/files/uploads": { "post": { "operationId": "startUpload", "description": "Opens an upload session for one file of `size` bytes in the folder\n`path`, or resumes the session of this access key for the same file\n(folder, name, size and `modified_at`): `received` lists the chunks\nit already holds. Send the file in chunks of `chunk_size` bytes with\nuploadChunk, then finishUpload. A session lives 24 hours. Files above\n`FILE_MANAGER_UPLOAD_MAX` answer `413` `E_LIMIT`, a full disk quota\n`422` `E_LIMIT` (when the server enforces quotas), too little space\nin the panel's staging folder `507` `E_DISK`.", "summary": "Start or resume an upload", "tags": [ "Files" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartUploadRequest" } } } }, "responses": { "200": { "description": "The session, new or resumed; with `dry_run`, the planned steps of finishUpload.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "type": "object", "properties": { "token": { "type": "string", "description": "the session's token for uploadChunk, finishUpload and cancelUpload" }, "chunk_size": { "type": "integer", "description": "bytes of every chunk but the last" }, "chunks": { "type": "integer", "description": "number of chunks, indexes 0 to `chunks` − 1" }, "received": { "type": "array", "description": "indexes of the chunks the session already holds", "items": { "type": "integer" } } }, "required": [ "token", "chunk_size", "chunks", "received" ] } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/TooLarge" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" }, "507": { "$ref": "#/components/responses/InsufficientStorage" } } } }, "/users/{user}/files/uploads/{token}": { "delete": { "operationId": "cancelUpload", "description": "Ends the session and removes its chunks. Takes no `dry_run`.", "summary": "Cancel an upload", "tags": [ "Files" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/files/uploads/{token}/finish": { "post": { "operationId": "finishUpload", "description": "Assembles the chunks and writes the file as the user, with mode\n`0644`, creating the folders of `relative_path`. A file that exists\nanswers `409` `E_EXISTS` with `conflicts` unless `on_conflict` says\notherwise; with `skip` the upload is dropped and the answer is `200`\nwith the existing file. All chunks must have arrived (`422`\notherwise). The session ends here, also when the write fails; a full\ndisk quota answers `422` `E_LIMIT`.", "summary": "Finish an upload", "tags": [ "Files" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FinishUploadRequest" } } } }, "responses": { "200": { "description": "The existing file when `on_conflict` is `skip` and a file was in the way (nothing was written); with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FileEntry" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "201": { "description": "The uploaded file.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FileEntry" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" }, "Location": { "$ref": "#/components/headers/Location" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/TooLarge" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" }, "507": { "$ref": "#/components/responses/InsufficientStorage" } } } }, "/users/{user}/files/uploads/{token}/{index}": { "put": { "operationId": "uploadChunk", "description": "The raw bytes of chunk `index` (from 0) as the request body\n(`application/octet-stream`): exactly `chunk_size` bytes, the last\nchunk the rest of the file. A chunk sent again replaces the one\nstored. Chunks have their own rate limit of 600 requests a minute per\naccess key. Takes no `dry_run`.", "summary": "Upload a chunk", "tags": [ "Files" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "index", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "No content.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" }, "507": { "$ref": "#/components/responses/InsufficientStorage" } }, "requestBody": { "required": true, "description": "The bytes of the chunk: `chunk_size` bytes, the last chunk the rest of the file.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } } } }, "/users/{user}/logs": { "get": { "operationId": "listUserLogs", "description": "Newest first: `limit` entries (default 100) after skipping `offset`\nnewer ones; `meta.more` says whether older entries exist.", "summary": "List the action log of a user", "tags": [ "Logs" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Entries to return, from 1 to 1000. Defaults to 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } }, { "name": "offset", "in": "query", "description": "Newer entries to skip, from 0 to 8999.", "schema": { "type": "integer", "minimum": 0, "maximum": 8999, "default": 0 } } ], "responses": { "200": { "description": "Array of `LogEntry`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LogEntry" } }, "meta": { "$ref": "#/components/schemas/LogListMeta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "clearUserLogs", "description": "Administrators clear any log; users and resellers their own when\nPOLICY_USER_DELETE_LOGS allows it.", "summary": "Clear the action log of a user", "tags": [ "Logs" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "204": { "description": "No content.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/mail-domains": { "get": { "operationId": "listMailDomains", "summary": "List the mail domains of a user", "tags": [ "Mail" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size, from 1 to 1000. Without it the list is complete.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "offset", "in": "query", "description": "Items to skip. Used when `limit` is set; 0 when omitted.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Array of `MailDomain`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MailDomain" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "createMailDomain", "description": "Spam filter, anti-virus and DKIM follow the add page: on when left out\nand the server offers them. A domain the user has answers 409 `E_EXISTS`.", "summary": "Create a mail domain", "tags": [ "Mail" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreMailDomainRequest" } } } }, "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "201": { "description": "`MailDomain`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MailDomain" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" }, "Location": { "$ref": "#/components/headers/Location" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/mail-domains/{domain}": { "get": { "operationId": "getMailDomain", "summary": "Get a mail domain", "tags": [ "Mail" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`MailDomain`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MailDomain" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "operationId": "updateMailDomain", "description": "The General tab. Fields left out keep their value. `rate_limit` is for\nadministrators.", "summary": "Update a mail domain", "tags": [ "Mail" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMailDomainRequest" } } } }, "responses": { "200": { "description": "`MailDomain`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MailDomain" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "delete": { "operationId": "deleteMailDomain", "summary": "Delete a mail domain", "tags": [ "Mail" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "204": { "description": "No content.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/mail-domains/{domain}/accounts": { "get": { "operationId": "listMailAccounts", "summary": "List the mail accounts of a domain", "tags": [ "Mail" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size, from 1 to 1000. Without it the list is complete.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "offset", "in": "query", "description": "Items to skip. Used when `limit` is set; 0 when omitted.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Array of `MailAccount`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MailAccount" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "createMailAccount", "description": "An account the domain has answers 409 `E_EXISTS`. When `send_credentials_to`\nis sent, `meta.credentials_sent` says whether the settings mail went out.", "summary": "Create a mail account", "tags": [ "Mail" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/StoreMailAccountRequest" }, { "type": "object", "properties": { "discard_all": { "type": "boolean", "default": false } } } ] } } } }, "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "201": { "description": "`MailAccount`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MailAccount" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" }, "Location": { "$ref": "#/components/headers/Location" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/mail-domains/{domain}/accounts/{account}": { "get": { "operationId": "getMailAccount", "summary": "Get a mail account", "tags": [ "Mail" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "account", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`MailAccount`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MailAccount" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "operationId": "updateMailAccount", "description": "A field left out keeps its value. `aliases` and `forwards` replace the lists.\n`discard_all` together with `forwards` is a validation error.", "summary": "Update a mail account", "tags": [ "Mail" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "account", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMailAccountRequest" } } } }, "responses": { "200": { "description": "`MailAccount`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MailAccount" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "delete": { "operationId": "deleteMailAccount", "summary": "Delete a mail account", "tags": [ "Mail" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "account", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "204": { "description": "No content.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/mail-domains/{domain}/accounts/{account}/password": { "put": { "operationId": "changeMailAccountPassword", "summary": "Change the password of a mail account", "tags": [ "Mail" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "account", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeMailAccountPasswordRequest" } } } }, "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "204": { "description": "No content.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/mail-domains/{domain}/accounts/{account}/suspend": { "post": { "operationId": "suspendMailAccount", "summary": "Suspend a mail account", "tags": [ "Mail" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "account", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "`MailAccount`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MailAccount" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/mail-domains/{domain}/accounts/{account}/unsuspend": { "post": { "operationId": "unsuspendMailAccount", "summary": "Unsuspend a mail account", "tags": [ "Mail" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "account", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "`MailAccount`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MailAccount" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/mail-domains/{domain}/dns-records": { "get": { "operationId": "getMailDomainDnsRecords", "summary": "DNS records a mail domain needs", "tags": [ "Mail" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Array of `MailDnsRecord`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MailDnsRecord" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/users/{user}/mail-domains/{domain}/letsencrypt": { "post": { "operationId": "requestMailDomainLetsEncrypt", "description": "Answers 202 with the domain as it is: `ssl.letsencrypt` turns true once\nthe queued certificate is installed.", "summary": "Queue a Let's Encrypt certificate", "tags": [ "Mail" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestMailLetsEncryptRequest" } } } }, "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "202": { "description": "`MailDomain`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MailDomain" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" }, "Location": { "$ref": "#/components/headers/Location" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/mail-domains/{domain}/rebuild": { "post": { "operationId": "rebuildMailDomain", "description": "Administrators only.", "summary": "Rebuild a mail domain", "tags": [ "Mail" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "`MailDomain`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MailDomain" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/mail-domains/{domain}/smtp-relay": { "put": { "operationId": "setMailDomainSmtpRelay", "description": "Re-added only when the host, username or port changed or a password was sent.", "summary": "Set the SMTP relay", "tags": [ "Mail" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetMailDomainRelayRequest" } } } }, "responses": { "200": { "description": "`MailDomain`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MailDomain" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "delete": { "operationId": "deleteMailDomainSmtpRelay", "description": "Idempotent: 204 when the domain has no relay.", "summary": "Remove the SMTP relay", "tags": [ "Mail" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "204": { "description": "No content.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/mail-domains/{domain}/ssl": { "put": { "operationId": "setMailDomainSsl", "description": "Replacing a Let's Encrypt certificate removes it first, in the same plan.", "summary": "Install an uploaded certificate", "tags": [ "Mail" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetMailDomainSslRequest" } } } }, "responses": { "200": { "description": "`MailDomain`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MailDomain" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "delete": { "operationId": "deleteMailDomainSsl", "description": "Idempotent: 204 when the domain has no SSL.", "summary": "Remove the certificate of a mail domain", "tags": [ "Mail" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "204": { "description": "No content.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/mail-domains/{domain}/suspend": { "post": { "operationId": "suspendMailDomain", "summary": "Suspend a mail domain", "tags": [ "Mail" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "`MailDomain`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MailDomain" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/mail-domains/{domain}/unsuspend": { "post": { "operationId": "unsuspendMailDomain", "summary": "Unsuspend a mail domain", "tags": [ "Mail" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "`MailDomain`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MailDomain" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/malware/findings": { "get": { "operationId": "listMalwareFindings", "description": "Most severe first. Quarantined and ignored files are not listed.", "summary": "List the open malware findings of a user", "tags": [ "Malware scan" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size, from 1 to 1000. Without it the list is complete.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "offset", "in": "query", "description": "Items to skip. Used when `limit` is set; 0 when omitted.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Array of `MalwareFinding`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MalwareFinding" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/users/{user}/malware/findings/{finding}/ignore": { "post": { "operationId": "ignoreMalwareFinding", "description": "Adds the SHA-256 of the file to the ignore list of the user: files\nwith this content are not reported again.", "summary": "Mark a finding as not malware", "tags": [ "Malware scan" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "finding", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "204": { "description": "No content.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/malware/findings/{finding}/quarantine": { "post": { "operationId": "quarantineMalwareFinding", "description": "The file is read and removed as the user and kept in a root-only\nstore. A file that changed since the scan answers 422 `E_INVALID`:\nscan again first.", "summary": "Move the file of a finding to quarantine", "tags": [ "Malware scan" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "finding", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "`MalwareQuarantine`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MalwareQuarantine" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/malware/ignores": { "get": { "operationId": "listMalwareIgnores", "summary": "List the files a user marked as not malware", "tags": [ "Malware scan" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size, from 1 to 1000. Without it the list is complete.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "offset", "in": "query", "description": "Items to skip. Used when `limit` is set; 0 when omitted.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Array of `MalwareIgnore`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MalwareIgnore" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/users/{user}/malware/ignores/{sha256}": { "delete": { "operationId": "deleteMalwareIgnore", "description": "Removes a SHA-256 from the ignore list of the user.", "summary": "Report a file content again", "tags": [ "Malware scan" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "sha256", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "204": { "description": "No content.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/malware/quarantine": { "get": { "operationId": "listMalwareQuarantine", "summary": "List the quarantined files of a user", "tags": [ "Malware scan" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size, from 1 to 1000. Without it the list is complete.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "offset", "in": "query", "description": "Items to skip. Used when `limit` is set; 0 when omitted.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Array of `MalwareQuarantine`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MalwareQuarantine" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/users/{user}/malware/quarantine/{id}": { "delete": { "operationId": "deleteMalwareQuarantine", "summary": "Delete a quarantined file", "tags": [ "Malware scan" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "204": { "description": "No content.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/malware/quarantine/{id}/restore": { "post": { "operationId": "restoreMalwareQuarantine", "description": "Writes the file back to its path as the user, with its permissions.\nA file at that path answers 409 `E_EXISTS`, a missing folder 404\n`E_NOTEXIST`. The next scan reports the file again unless it is\nignored.", "summary": "Restore a quarantined file", "tags": [ "Malware scan" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "204": { "description": "No content.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/malware/scans": { "get": { "operationId": "listMalwareScans", "description": "The 30 newest scan records, newest first.", "summary": "List the malware scans of a user", "tags": [ "Malware scan" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size, from 1 to 1000. Without it the list is complete.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "offset", "in": "query", "description": "Items to skip. Used when `limit` is set; 0 when omitted.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Array of `MalwareScan`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MalwareScan" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "startMalwareScan", "description": "A full scan of one web domain, or of every web domain of the user, in\nthe background; follow the task. A scan of the user that is already\nrunning answers 409 `E_INUSE` with the running task in `existing`.", "summary": "Start a malware scan", "tags": [ "Malware scan" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartMalwareScanRequest" } } } }, "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "202": { "description": "`Task`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Task" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" }, "Location": { "$ref": "#/components/headers/Location" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/node": { "get": { "operationId": "getNodeAccount", "summary": "Get the Node.js account of a user", "tags": [ "Node.js" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`NodeAccount`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/NodeAccount" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "setNodeEnabled", "summary": "Enable or remove Node.js for a user", "tags": [ "Node.js" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetNodeEnabledRequest" } } } }, "responses": { "200": { "description": "`NodeAccount`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/NodeAccount" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/node-apps": { "get": { "operationId": "listNodeApps", "summary": "List the Node.js apps of a user", "tags": [ "Node.js apps" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Array of `NodeApp`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/NodeApp" } }, "meta": { "$ref": "#/components/schemas/NodeAppListMeta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "createNodeApp", "summary": "Create a Node.js app", "tags": [ "Node.js apps" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreNodeAppRequest" } } } }, "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "201": { "description": "`NodeApp`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/NodeApp" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" }, "Location": { "$ref": "#/components/headers/Location" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/node-apps/detect/{domain}": { "get": { "operationId": "detectNodeApp", "summary": "Detect what package.json proposes for an app", "tags": [ "Node.js apps" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "cwd", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^(\\.|[A-Za-z0-9_][A-Za-z0-9._\\/@+-]{0,199})$" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "package_json": { "type": "string" }, "start": { "type": "string" }, "template": { "type": "string" }, "scripts": { "type": "string" } }, "required": [ "package_json", "start", "template", "scripts" ] } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/users/{user}/node-apps/{domain}": { "get": { "operationId": "getNodeApp", "summary": "Get a Node.js app", "tags": [ "Node.js apps" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`NodeApp`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/NodeApp" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "operationId": "updateNodeApp", "summary": "Update a Node.js app", "tags": [ "Node.js apps" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateNodeAppRequest" } } } }, "responses": { "200": { "description": "`NodeApp`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/NodeApp" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "delete": { "operationId": "deleteNodeApp", "summary": "Delete a Node.js app", "tags": [ "Node.js apps" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "keep_files", "in": "query", "schema": { "type": "boolean", "default": false } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "204": { "description": "No content.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/node-apps/{domain}/build": { "post": { "operationId": "buildNodeApp", "summary": "Run an npm script on a Node.js app", "tags": [ "Node.js apps" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuildNodeAppRequest" } } } }, "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "202": { "description": "`Task`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Task" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" }, "Link": { "$ref": "#/components/headers/Link" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/node-apps/{domain}/env": { "get": { "operationId": "getNodeAppEnv", "summary": "List the environment of a Node.js app", "tags": [ "Node.js apps" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "reveal", "in": "query", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Environment names and set flags (D41); values only with `reveal=1`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/NodeAppEnvEntry" } } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "setNodeAppEnv", "summary": "Replace the environment of a Node.js app", "tags": [ "Node.js apps" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetNodeAppEnvRequest" } } } }, "responses": { "200": { "description": "The saved environment (names and set flags; values only when the key may reveal them); with `dry_run`, the planned steps.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/NodeAppEnvEntry" } } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/node-apps/{domain}/install": { "post": { "operationId": "installNodeApp", "description": "Chooses the install command from the lockfile in the app working directory\n(`pnpm-lock.yaml`, `yarn.lock`, or `package-lock.json`), otherwise\n`npm install`, as the panel install control does. There is no request\nfield to override it.", "summary": "Install npm dependencies of a Node.js app", "tags": [ "Node.js apps" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "202": { "description": "`Task`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Task" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" }, "Link": { "$ref": "#/components/headers/Link" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/node-apps/{domain}/logs": { "get": { "operationId": "getNodeAppLogs", "summary": "Read a snapshot of Node.js app logs", "tags": [ "Node.js apps" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "lines", "in": "query", "description": "Number of lines to return (1–1000). Defaults to 200.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 200 } }, { "name": "after", "in": "query", "description": "Opaque cursor from `meta.next` of a previous snapshot; returns lines that appeared since.", "schema": { "type": "string", "maxLength": 64 } }, { "name": "stream", "in": "query", "description": "Which log file to read.", "schema": { "type": "string", "enum": [ "out", "err", "install", "build" ], "default": "out" } } ], "responses": { "200": { "description": "Log lines and a cursor for the next snapshot (D43).", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "lines": { "type": "array", "items": {} } }, "required": [ "lines" ] }, "meta": { "$ref": "#/components/schemas/NodeAppLogMeta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/users/{user}/node-apps/{domain}/reload": { "post": { "operationId": "reloadNodeApp", "summary": "Reload a Node.js app", "tags": [ "Node.js apps" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "`NodeApp`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/NodeApp" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/node-apps/{domain}/restart": { "post": { "operationId": "restartNodeApp", "summary": "Restart a Node.js app", "tags": [ "Node.js apps" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "`NodeApp`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/NodeApp" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/node-apps/{domain}/start": { "post": { "operationId": "startNodeApp", "summary": "Start a Node.js app", "tags": [ "Node.js apps" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "`NodeApp`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/NodeApp" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/node-apps/{domain}/stop": { "post": { "operationId": "stopNodeApp", "summary": "Stop a Node.js app", "tags": [ "Node.js apps" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "`NodeApp`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/NodeApp" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/node/releases": { "get": { "operationId": "listNodeReleases", "summary": "List installable Node.js majors", "tags": [ "Node.js" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size, from 1 to 1000. Without it the list is complete.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "offset", "in": "query", "description": "Items to skip. Used when `limit` is set; 0 when omitted.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Array of `NodeRelease`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/NodeRelease" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/users/{user}/node/versions": { "get": { "operationId": "listNodeVersions", "summary": "List the installed Node.js runtimes of a user", "tags": [ "Node.js" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size, from 1 to 1000. Without it the list is complete.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "offset", "in": "query", "description": "Items to skip. Used when `limit` is set; 0 when omitted.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Array of `NodeRuntime`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/NodeRuntime" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "installNodeVersion", "summary": "Install a Node.js runtime", "tags": [ "Node.js" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstallNodeVersionRequest" } } } }, "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "202": { "description": "`Task`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Task" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" }, "Link": { "$ref": "#/components/headers/Link" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/node/versions/{version}": { "delete": { "operationId": "deleteNodeVersion", "summary": "Uninstall a Node.js runtime", "tags": [ "Node.js" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "204": { "description": "No content.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/node/versions/{version}/default": { "put": { "operationId": "setNodeDefaultVersion", "summary": "Set the default Node.js runtime", "tags": [ "Node.js" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "`NodeAccount`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/NodeAccount" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/node/versions/{version}/packages": { "get": { "operationId": "listNodePackages", "summary": "List the global npm packages of a runtime", "tags": [ "Node.js" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size, from 1 to 1000. Without it the list is complete.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "offset", "in": "query", "description": "Items to skip. Used when `limit` is set; 0 when omitted.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Array of `NodePackage`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/NodePackage" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "installNodePackage", "summary": "Install a global npm package", "tags": [ "Node.js" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstallNodePackageRequest" } } } }, "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "202": { "description": "`Task`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Task" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" }, "Link": { "$ref": "#/components/headers/Link" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/node/versions/{version}/packages/check": { "post": { "operationId": "checkNodePackages", "summary": "Check global npm packages for updates", "tags": [ "Node.js" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "202": { "description": "`Task`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Task" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" }, "Link": { "$ref": "#/components/headers/Link" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/node/versions/{version}/packages/update": { "post": { "operationId": "updateNodePackages", "summary": "Update every global npm package of a runtime", "tags": [ "Node.js" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "202": { "description": "`Task`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Task" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" }, "Link": { "$ref": "#/components/headers/Link" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/node/versions/{version}/packages/{package}": { "delete": { "operationId": "deleteNodePackage", "summary": "Remove a global npm package", "tags": [ "Node.js" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "package", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "204": { "description": "No content.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/package": { "put": { "operationId": "changeUserPackage", "summary": "Change the package of a user", "tags": [ "Users" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserPackageRequest" } } } }, "responses": { "200": { "description": "`User`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/User" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/password": { "put": { "operationId": "changeUserPassword", "summary": "Change the password of a user", "tags": [ "Users" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserPasswordRequest" } } } }, "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "204": { "description": "No content.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/ports": { "get": { "operationId": "listPorts", "description": "The entries of the user's pool: single ports (free or assigned to an\napp) and free ranges. `meta` holds the totals of the pool and the\nserver range; the list is not paginated.", "summary": "List the ports of a user", "tags": [ "Ports" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The ports of the account with the totals of its pool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PortEntry" } }, "meta": { "$ref": "#/components/schemas/PortListMeta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/users/{user}/ports/give": { "post": { "operationId": "givePorts", "description": "Moves free ports of `{user}`'s pool to `to`, one of its customers: a\n`range` of free ports, or the `count` lowest free ones. Administrators\nand resellers only (`PortPolicy::give`). Answers the ports of `to`.", "summary": "Give ports to a customer", "tags": [ "Ports" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GivePortsRequest" } } } }, "responses": { "200": { "description": "The ports of the account with the totals of its pool; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PortEntry" } }, "meta": { "$ref": "#/components/schemas/PortListMeta" } }, "required": [ "data", "meta" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/ports/request": { "post": { "operationId": "requestPorts", "description": "Sends a notification to the owner of the user (its reseller, or the\nadministrator). Only for the key's own account, never by an\nadministrator.", "summary": "Ask for more ports", "tags": [ "Ports" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestPortsRequest" } } } }, "responses": { "200": { "description": "The owner that was notified and the count asked for; with `dry_run`, the planned steps.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "type": "object", "properties": { "owner": { "type": "string", "description": "The reseller or administrator that received the notification." }, "count": { "type": "integer", "minimum": 1 } }, "required": [ "owner", "count" ] } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/ports/reserve": { "post": { "operationId": "reservePort", "description": "Assigns a port of the user's own pool (the first free one, or `port`)\nto `manual` use, as \"Reserve a port\" on the page.", "summary": "Reserve a port", "tags": [ "Ports" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReservePortRequest" } } } }, "responses": { "200": { "description": "`PortEntry`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PortEntry" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/ports/{range}": { "delete": { "operationId": "deletePorts", "description": "Administrators only. `?force=1` also deletes assigned ports.", "summary": "Delete ports of a user", "tags": [ "Ports" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "range", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{1,5}(-\\d{1,5})?$" }, "description": "A port (`30005`) or a range (`30010-30019`)." }, { "name": "force", "in": "query", "schema": { "type": "boolean", "default": false } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "204": { "description": "No content.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/ports/{range}/public": { "put": { "operationId": "setPortPublic", "description": "Only an assigned single port; opening needs `public_ok`. Administrators\nmay pass `rule` to link an existing firewall rule on the port.", "summary": "Open or close a port to the internet", "tags": [ "Ports" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "range", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{1,5}(-\\d{1,5})?$" }, "description": "A port (`30005`) or a range (`30010-30019`)." }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } }, { "name": "proto", "in": "query", "description": "Act only when the port is used with this protocol (404 otherwise).", "schema": { "type": "string", "enum": [ "tcp", "udp" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetPortPublicRequest" } } } }, "responses": { "200": { "description": "`PortEntry`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PortEntry" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/ports/{range}/public-ok": { "put": { "operationId": "setPortPublicOk", "description": "Administrators either way; a reseller may only forbid them on its\ncustomers' ports.", "summary": "Allow or forbid public ports", "tags": [ "Ports" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "range", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{1,5}(-\\d{1,5})?$" }, "description": "A port (`30005`) or a range (`30010-30019`)." }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetPortPublicOkRequest" } } } }, "responses": { "200": { "description": "The ports of the account with the totals of its pool; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PortEntry" } }, "meta": { "$ref": "#/components/schemas/PortListMeta" } }, "required": [ "data", "meta" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/ports/{range}/reclaim": { "post": { "operationId": "reclaimPorts", "description": "Moves free ports of a customer back into its reseller's pool.", "summary": "Take free ports back", "tags": [ "Ports" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "range", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{1,5}(-\\d{1,5})?$" }, "description": "A port (`30005`) or a range (`30010-30019`)." }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "The ports of the account with the totals of its pool; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PortEntry" } }, "meta": { "$ref": "#/components/schemas/PortListMeta" } }, "required": [ "data", "meta" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/ports/{range}/release": { "post": { "operationId": "releasePort", "description": "Frees a port the user reserved or an app holds; it stays in the pool.", "summary": "Release a port", "tags": [ "Ports" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "range", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{1,5}(-\\d{1,5})?$" }, "description": "A port (`30005`) or a range (`30010-30019`)." }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } }, { "name": "proto", "in": "query", "description": "Act only when the port is used with this protocol (404 otherwise).", "schema": { "type": "string", "enum": [ "tcp", "udp" ] } } ], "responses": { "200": { "description": "The ports of the account with the totals of its pool; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PortEntry" } }, "meta": { "$ref": "#/components/schemas/PortListMeta" } }, "required": [ "data", "meta" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/secrets": { "get": { "operationId": "listSecrets", "description": "Sorted by name; values are never listed.", "summary": "List the secrets of a user", "tags": [ "Secrets" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size, from 1 to 1000. Without it the list is complete.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "offset", "in": "query", "description": "Items to skip. Used when `limit` is set; 0 when omitted.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Array of `UserSecret`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/UserSecret" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "createSecret", "description": "The value is stored as version 1, encrypted with the user's key.\nA name that exists answers 409 `E_EXISTS`, more secrets than the\nserver allows 422 `E_LIMIT`.", "summary": "Create a secret", "tags": [ "Secrets" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUserSecretRequest" } } } }, "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "201": { "description": "`UserSecret`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/UserSecret" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" }, "Location": { "$ref": "#/components/headers/Location" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/secrets/{name}": { "get": { "operationId": "getSecret", "description": "Its kept versions and the apps that reference it; never the value.", "summary": "Show a secret", "tags": [ "Secrets" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The secret name, with or without its leading slash: `/shop/db` (encoded as `%2Fshop%2Fdb`) or `shop/db`." } ], "responses": { "200": { "description": "`UserSecret`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/UserSecret" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "operationId": "updateSecret", "summary": "Change the description of a secret", "tags": [ "Secrets" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The secret name, with or without its leading slash: `/shop/db` (encoded as `%2Fshop%2Fdb`) or `shop/db`." }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUserSecretRequest" } } } }, "responses": { "200": { "description": "`UserSecret`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/UserSecret" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "delete": { "operationId": "deleteSecret", "description": "A secret that an app references answers 409 `E_INUSE` with `used_by`,\nunless `force=1`; such apps then fail to start until the reference is\nremoved or the secret is added again.", "summary": "Delete a secret", "tags": [ "Secrets" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The secret name, with or without its leading slash: `/shop/db` (encoded as `%2Fshop%2Fdb`) or `shop/db`." }, { "name": "force", "in": "query", "schema": { "type": "boolean", "default": false } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "204": { "description": "No content.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/secrets/{name}/rollback": { "post": { "operationId": "rollbackSecret", "description": "Copies the version into a new one, like putSecretValue.", "summary": "Roll a secret back to a kept version", "tags": [ "Secrets" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The secret name, with or without its leading slash: `/shop/db` (encoded as `%2Fshop%2Fdb`) or `shop/db`." }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RollbackUserSecretRequest" } } } }, "responses": { "200": { "description": "; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "type": "object", "properties": { "secret": { "type": "array", "items": {} }, "apps": { "type": "array", "description": "the apps that reference the secret", "items": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } }, "required": [ "type", "id" ] } }, "restarted": { "type": "boolean", "description": "whether the running ones were restarted" }, "failed": { "type": "array", "description": "running apps that did not restart; the value is changed anyway", "items": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } }, "required": [ "type", "id" ] } } }, "required": [ "secret", "apps", "restarted", "failed" ] } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/secrets/{name}/value": { "put": { "operationId": "putSecretValue", "description": "Stores the next version (the last five are kept) and answers the apps\nthat reference the secret. With `restart` the running ones are\nrestarted, so they read the new value; otherwise they keep the old\nvalue until their next start. A value that one of those apps cannot\ntake (several lines, or quotes for a Docker app) answers 422\n`E_INVALID` and changes nothing.", "summary": "Replace the value of a secret", "tags": [ "Secrets" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The secret name, with or without its leading slash: `/shop/db` (encoded as `%2Fshop%2Fdb`) or `shop/db`." }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutUserSecretValueRequest" } } } }, "responses": { "200": { "description": "; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "type": "object", "properties": { "secret": { "type": "array", "items": {} }, "apps": { "type": "array", "description": "the apps that reference the secret", "items": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } }, "required": [ "type", "id" ] } }, "restarted": { "type": "boolean", "description": "whether the running ones were restarted" }, "failed": { "type": "array", "description": "running apps that did not restart; the value is changed anyway", "items": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } }, "required": [ "type", "id" ] } } }, "required": [ "secret", "apps", "restarted", "failed" ] } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/snapshots": { "post": { "operationId": "createSnapshot", "description": "Queues a snapshot of the user. When a backup or restore is already queued,\nanswers 409 `E_EXISTS` with `existing` set to that task.", "summary": "Create a restic snapshot", "tags": [ "Backups" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "202": { "description": "`Task`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Task" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" }, "Location": { "$ref": "#/components/headers/Location" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "get": { "operationId": "listSnapshots", "description": "Newest first. Only available when the user's package has incremental backups.", "summary": "List restic snapshots of a user", "tags": [ "Backups" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size, from 1 to 1000. Without it the list is complete.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "offset", "in": "query", "description": "Items to skip. Used when `limit` is set; 0 when omitted.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Array of `Snapshot`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Snapshot" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/users/{user}/snapshots/{snapshot}": { "delete": { "operationId": "deleteSnapshot", "summary": "Delete a restic snapshot", "tags": [ "Backups" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "snapshot", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "204": { "description": "No content.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "get": { "operationId": "getSnapshot", "description": "Includes the objects the snapshot holds per type.", "summary": "Get a restic snapshot", "tags": [ "Backups" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "snapshot", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`Snapshot`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Snapshot" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/users/{user}/snapshots/{snapshot}/files": { "get": { "operationId": "listSnapshotFiles", "description": "Paths are relative to the home directory. Entries are read-only.", "summary": "List files and folders in a restic snapshot", "tags": [ "Backups" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "snapshot", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size, from 1 to 1000. Without it the list is complete.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "offset", "in": "query", "description": "Items to skip. Used when `limit` is set; 0 when omitted.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Array of `SnapshotFileEntry`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SnapshotFileEntry" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/users/{user}/snapshots/{snapshot}/restore": { "post": { "operationId": "restoreSnapshot", "description": "An empty body restores everything. Send `type` and `object` to restore one\nweb, dns, mail or database object, or all cron jobs. Send `path` to restore\none file or folder; the restore overwrites the current file.", "summary": "Restore from a restic snapshot", "tags": [ "Backups" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "snapshot", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestoreSnapshotRequest" } } } }, "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "202": { "description": "`Task`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Task" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" }, "Location": { "$ref": "#/components/headers/Location" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/ssh-keys": { "get": { "operationId": "listSshKeys", "summary": "List the SSH keys of a user", "tags": [ "SSH keys" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size, from 1 to 1000. Without it the list is complete.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "offset", "in": "query", "description": "Items to skip. Used when `limit` is set; 0 when omitted.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Array of `SshKey`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SshKey" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "addSshKey", "description": "A key line without a comment gets one. A key whose comment or\nfingerprint the user already has answers 409 `E_EXISTS`.", "summary": "Add an SSH key", "tags": [ "SSH keys" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddSshKeyRequest" } } } }, "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "201": { "description": "`SshKey`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SshKey" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" }, "Location": { "$ref": "#/components/headers/Location" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/ssh-keys/{id}": { "delete": { "operationId": "deleteSshKey", "description": "`id` is the key's comment, URL-encoded.", "summary": "Delete an SSH key", "tags": [ "SSH keys" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "204": { "description": "No content.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/stats": { "get": { "operationId": "listUserStats", "description": "Newest first.", "summary": "List the monthly statistics of a user", "tags": [ "Statistics" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size, from 1 to 1000. Without it the list is complete.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "offset", "in": "query", "description": "Items to skip. Used when `limit` is set; 0 when omitted.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Array of `StatsMonth`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StatsMonth" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/users/{user}/suspend": { "post": { "operationId": "suspendUser", "description": "Suspends the account and its objects; a suspended user answers as it is.", "summary": "Suspend a user", "tags": [ "Users" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "`User`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/User" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/tasks": { "get": { "operationId": "listUserTasks", "description": "Node.js, Quick Install, Docker apps and queue tasks of the last seven\ndays, newest first. Paged with `limit` and `offset` (D20).", "summary": "List the tasks of a user", "tags": [ "Tasks" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size, from 1 to 1000. Without it the list is complete.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "offset", "in": "query", "description": "Items to skip. Used when `limit` is set; 0 when omitted.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Array of `Task`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Task" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/users/{user}/two-factor": { "delete": { "operationId": "disableUserTwoFactor", "description": "Users for their own account, administrators for the accounts they\nmanage. Turning it on stays with the login of the user. Answers 204\nwithout a command when it is already off.", "summary": "Turn off two-factor authentication", "tags": [ "Users" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "204": { "description": "No content.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/unsuspend": { "post": { "operationId": "unsuspendUser", "summary": "Unsuspend a user", "tags": [ "Users" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "`User`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/User" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/web-domains": { "get": { "operationId": "listWebDomains", "summary": "List the web domains of a user", "tags": [ "Web domains" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size, from 1 to 1000. Without it the list is complete.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "offset", "in": "query", "description": "Items to skip. Used when `limit` is set; 0 when omitted.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Array of `WebDomain`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebDomain" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "createWebDomain", "description": "As the add page of the panel: the domain with its aliases (`www.DOMAIN`\nby default), the DNS zone and mail domain when asked, then the asked\ntemplates and the app port of a template that takes one. A domain the\nuser has answers 409 `E_EXISTS`; one of another user fails with it too.", "summary": "Create a web domain", "tags": [ "Web domains" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreWebDomainRequest" } } } }, "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "201": { "description": "`WebDomain`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebDomain" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" }, "Location": { "$ref": "#/components/headers/Location" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/web-domains/{domain}": { "get": { "operationId": "getWebDomain", "summary": "Get a web domain", "tags": [ "Web domains" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`WebDomain`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebDomain" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "operationId": "updateWebDomain", "description": "The IP address, the document root and, with the right to change\ntemplates, the templates, proxy, FastCGI cache and app port; the fields\nleft out keep their value. A new IP also moves the DNS zones of the\ndomain and its aliases.", "summary": "Update a web domain", "tags": [ "Web domains" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebDomainRequest" } } } }, "responses": { "200": { "description": "`WebDomain`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebDomain" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "delete": { "operationId": "deleteWebDomain", "description": "Deletes the domain with its files, and the app port, Node.js app and\nDocker app bound to it (the Docker app's data folder is kept).", "summary": "Delete a web domain", "tags": [ "Web domains" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "204": { "description": "No content.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/web-domains/{domain}/aliases": { "post": { "operationId": "addWebDomainAlias", "description": "With a DNS record when the domain has a DNS zone; a Let's Encrypt\ncertificate is queued again to cover it. An alias the domain has\nanswers 409 `E_EXISTS`.", "summary": "Add an alias to a web domain", "tags": [ "Web domains" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebDomainAliasRequest" } } } }, "responses": { "200": { "description": "`WebDomain`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebDomain" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/web-domains/{domain}/aliases/{alias}": { "delete": { "operationId": "deleteWebDomainAlias", "description": "With its DNS record; a Let's Encrypt certificate is queued again\nwithout it.", "summary": "Delete an alias of a web domain", "tags": [ "Web domains" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "alias", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "204": { "description": "No content.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/web-domains/{domain}/letsencrypt": { "post": { "operationId": "requestWebDomainLetsEncrypt", "description": "Queues the certificate for the domain and its aliases, which must\nresolve to this server; the queue runs every five minutes. Answers\n202 with the domain as it is: `ssl.letsencrypt` turns true once the\ncertificate is installed.", "summary": "Request a Let's Encrypt certificate", "tags": [ "Web domains" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LetsEncryptRequest" } } } }, "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "202": { "description": "`WebDomain`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebDomain" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" }, "Location": { "$ref": "#/components/headers/Location" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/web-domains/{domain}/logs": { "get": { "operationId": "getWebDomainLogs", "description": "The error log by default, or the access log with `type=access`; the\nnewest line comes last (E37 spec §4.1).", "summary": "Read the last lines of a web domain log", "tags": [ "Web domains" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "type", "in": "query", "description": "Which log to read.", "schema": { "type": "string", "enum": [ "error", "access" ], "default": "error" } }, { "name": "lines", "in": "query", "description": "Number of lines to return (1–1000). Defaults to 200.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 200 } } ], "responses": { "200": { "description": "The last lines of the log, the newest last (E37 spec §4.1).", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "lines": { "type": "array", "items": { "type": "string" } } }, "required": [ "lines" ] }, "meta": { "$ref": "#/components/schemas/WebDomainLogMeta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/users/{user}/web-domains/{domain}/php": { "get": { "operationId": "getWebDomainPhp", "description": "Its version and profile, the versions and profiles the package allows,\nand the effective PHP limits with their source.", "summary": "Get the PHP of a web domain", "tags": [ "Web domains" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`WebDomainPhp`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebDomainPhp" } }, "required": [ "data" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "setWebDomainPhp", "description": "A new version changes the backend template to `PHP-X_Y`; the pool is\nwritten with the profile. Both must be allowed by the package of the\nowner unless the domain already has them (`403`).", "summary": "Set the PHP of a web domain", "tags": [ "Web domains" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetWebDomainPhpRequest" } } } }, "responses": { "200": { "description": "`WebDomainPhp`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebDomainPhp" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/web-domains/{domain}/purge-cache": { "post": { "operationId": "purgeWebDomainCache", "description": "On servers where NGINX serves the domains; 403 elsewhere.", "summary": "Purge the NGINX cache of a web domain", "tags": [ "Web domains" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "`WebDomain`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebDomain" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/web-domains/{domain}/rebuild": { "post": { "operationId": "rebuildWebDomain", "description": "Writes the configuration of the domain again. Administrators only.", "summary": "Rebuild a web domain", "tags": [ "Web domains" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "`WebDomain`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebDomain" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/web-domains/{domain}/ssl": { "put": { "operationId": "setWebDomainSsl", "description": "With `certificate` (and `key` for a first certificate) the uploaded\ncertificate is installed or replaced; a Let's Encrypt certificate is\nremoved first. Without it, `force` and `hsts` change for the\ncertificate the domain has.", "summary": "Install a certificate or change HTTPS settings", "tags": [ "Web domains" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebDomainSslRequest" } } } }, "responses": { "200": { "description": "`WebDomain`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebDomain" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "delete": { "operationId": "deleteWebDomainSsl", "description": "Removes the certificate (uploaded or Let's Encrypt), forced HTTPS and\nHSTS. A domain without SSL answers as it is.", "summary": "Turn SSL off", "tags": [ "Web domains" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "With `dry_run`: the planned steps; nothing ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "204": { "description": "No content.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/web-domains/{domain}/suspend": { "post": { "operationId": "suspendWebDomain", "description": "A suspended domain answers as it is.", "summary": "Suspend a web domain", "tags": [ "Web domains" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "`WebDomain`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebDomain" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/users/{user}/web-domains/{domain}/unsuspend": { "post": { "operationId": "unsuspendWebDomain", "summary": "Unsuspend a web domain", "tags": [ "Web domains" ], "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate, authorize and plan the change, and answer with its steps instead of running them.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "`WebDomain`; with `dry_run`, the planned steps.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebDomain" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/DryRun" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/web-domains": { "get": { "operationId": "listAllWebDomains", "description": "Every user's web domains for an administrator's key, those of the reseller\nand its customers for a reseller's key; a user's key answers 403\n(`listWebDomains` covers it). Sorted by user, then domain. With\n`updated_since`, only the users whose web domains changed at or after that\ntime are returned, each with all its web domains: `meta.as_of` is the next\n`updated_since`, `meta.users` every user in scope and\n`meta.changed_users` the users returned (E43 B2).", "summary": "List the web domains of every user", "tags": [ "Web domains" ], "responses": { "200": { "description": "Array of `WebDomain`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebDomain" } }, "meta": { "$ref": "#/components/schemas/CrossUserListMeta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "parameters": [ { "name": "user", "in": "query", "description": "One user in the scope of the key; the list then holds only that user. A user outside the scope answers 404.", "schema": { "type": "string", "pattern": "^[[:alnum:]][-.\\w]{0,28}[[:alnum:]]$" } }, { "name": "updated_since", "in": "query", "description": "ISO 8601 time, UTC without an offset: only the users whose objects of this kind changed at or after it, each with all its objects. Use the `meta.as_of` of the previous first page.", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "description": "Page size, from 1 to 1000. Without it the list is complete.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "offset", "in": "query", "description": "Items to skip. Used when `limit` is set; 0 when omitted.", "schema": { "type": "integer", "minimum": 0 } } ] } } }, "components": { "schemas": { "AccessKey": { "type": "object", "properties": { "id": { "type": "string", "description": "the access key id, 20 letters and digits" }, "permissions": { "type": "array", "description": "the permission sets; empty for an administrator's key without sets, which may run every command", "items": { "type": "string" } }, "comment": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "description": "in the server's time zone, YYYY-MM-DDTHH:MM:SS" }, "allowed_ips": { "type": "array", "description": "addresses and networks the key is limited to; empty when unrestricted (E43 B6)", "items": { "type": "string" } }, "expires_at": { "type": [ "string", "null" ], "description": "ISO 8601 time in UTC after which the key is refused; null without an expiry" } }, "required": [ "id", "permissions", "comment", "created_at", "allowed_ips", "expires_at" ], "title": "AccessKey" }, "AccessKeySet": { "type": "object", "properties": { "name": { "type": "string" }, "api": { "type": "integer", "description": "`2`: REST API v2 only, API v1 refuses the set; `1`: a set of API v1, whose commands API v2 runs too", "enum": [ 1, 2 ] }, "description": { "type": [ "string", "null" ] } }, "required": [ "name", "api", "description" ], "title": "AccessKeySet" }, "AddReservedPortsRequest": { "type": "object", "properties": { "range": { "type": "string", "pattern": "^\\d{1,5}(-\\d{1,5})?$" }, "comment": { "type": [ "string", "null" ], "pattern": "^[[:alnum:]][[:alnum:] ._-]{0,64}[[:alnum:]]$" } }, "required": [ "range" ], "title": "AddReservedPortsRequest" }, "AddSshKeyRequest": { "type": "object", "description": "POST /users/{user}/ssh-keys: one public key line of authorized_keys.", "properties": { "key": { "type": "string", "description": "The public key line: type, key and an optional comment, which identifies the key; a missing comment is generated. At most 16384 characters, one line.", "pattern": "^(ssh-rsa|ssh-dss|ssh-ed25519|ecdsa-sha2-nistp256|ecdsa-sha2-nistp384|ecdsa-sha2-nistp521|sk-ssh-ed25519@openssh\\.com|sk-ecdsa-sha2-nistp256@openssh\\.com) [A-Za-z0-9+\\/]+={0,3}( [^\\x00-\\x1f'\"]+)?$", "maxLength": 16384 } }, "required": [ "key" ], "title": "AddSshKeyRequest" }, "AdoptPortRuleRequest": { "type": "object", "properties": { "port": { "type": "integer", "minimum": 1, "maximum": 65535 }, "rule": { "type": "integer", "minimum": 1 } }, "required": [ "port", "rule" ], "title": "AdoptPortRuleRequest" }, "AllocatePortsRequest": { "type": "object", "properties": { "user": { "type": "string", "pattern": "^[[:alnum:]][-.\\w]{0,28}[[:alnum:]]$" }, "range": { "type": [ "string", "null" ], "pattern": "^\\d{1,5}(-\\d{1,5})?$" }, "count": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 10000 }, "public_ok": { "type": [ "boolean", "null" ] }, "comment": { "type": [ "string", "null" ], "pattern": "^[[:alnum:]][[:alnum:] ._-]{0,64}[[:alnum:]]$" } }, "required": [ "user" ], "title": "AllocatePortsRequest" }, "ApiRequest": { "type": "object", "properties": { "id": { "type": "string", "description": "the request id (`X-Request-Id`)" }, "operation": { "type": "string", "description": "the operationId" }, "method": { "type": "string" }, "path": { "type": "string", "description": "the path as called, without the query" }, "state": { "type": "string", "description": "`running` less than 15 minutes after the start without an end, `unknown` after that", "enum": [ "running", "finished", "unknown" ] }, "status": { "type": [ "integer", "null" ], "description": "HTTP status of the answer, null unless finished" }, "error_code": { "type": [ "string", "null" ], "description": "error code of a failed answer" }, "task_id": { "type": [ "string", "null" ], "description": "the task of a 202 answer (`GET /tasks/{id}`)" }, "location": { "type": [ "string", "null" ], "description": "the Location of a 201 or 202 answer" }, "started_at": { "type": "string", "description": "ISO 8601 (UTC)" }, "finished_at": { "type": [ "string", "null" ], "description": "ISO 8601 (UTC), null unless finished" } }, "required": [ "id", "operation", "method", "path", "state", "status", "error_code", "task_id", "location", "started_at", "finished_at" ], "title": "ApiRequest" }, "ApiRole": { "type": "string", "description": "Role of a user in API v2 answers and requests.\n", "enum": [ "admin", "reseller", "user" ], "title": "ApiRole" }, "AppProcess": { "type": "object", "properties": { "domain": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string" }, "preset": { "type": "string" }, "start": { "type": "string" }, "cwd": { "type": "string" }, "port": { "type": [ "integer", "null" ] }, "memory_mb": { "type": "string" }, "cpus": { "type": "string" }, "template": { "type": [ "string", "null" ] }, "state": { "type": "string" }, "status": { "type": "string" }, "running": { "type": "string" }, "suspended": { "type": "string" }, "pid": { "type": [ "string", "null" ] }, "memory_used_mb": { "type": "string" }, "cpu_seconds": { "type": "string" }, "restarts": { "type": "string" }, "uptime_seconds": { "type": "string" }, "reload": { "type": [ "string", "null" ] }, "runtime_missing": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] } }, "required": [ "domain", "name", "kind", "preset", "start", "cwd", "port", "memory_mb", "cpus", "template", "state", "status", "running", "suspended", "pid", "memory_used_mb", "cpu_seconds", "restarts", "uptime_seconds", "reload", "runtime_missing", "created_at" ], "title": "AppProcess" }, "AppProcessListMeta": { "type": "object", "description": "APP_PROCESSES limits of the user's package; the list is not paginated (E42).", "properties": { "allowed": { "type": "boolean", "description": "Whether the package allows app processes." }, "totals": { "type": "object", "properties": { "running": { "type": "integer" }, "stopped": { "type": "integer" }, "failed": { "type": "integer" }, "suspended": { "type": "integer" } }, "required": [ "running", "stopped", "failed", "suspended" ] }, "limit": { "type": "string", "description": "APP_PROCESSES_MAX: a number or `unlimited`." }, "room": { "type": "boolean", "description": "Whether another process fits." }, "max_memory_mb": { "type": "integer", "description": "Highest memory of one process." }, "default_memory_mb": { "type": "integer", "description": "Memory of a new process when none is given." }, "max_cpus": { "type": "string", "description": "APP_PROCESSES_CPUS: CPUs of one process, or `unlimited`." } }, "required": [ "allowed", "totals", "limit", "room", "max_memory_mb", "default_memory_mb", "max_cpus" ] }, "AppProcessLogMeta": { "type": "object", "description": "Cursor metadata for log snapshots.", "properties": { "stream": { "type": "string", "enum": [ "process", "task" ] }, "next": { "description": "Cursor for the next snapshot; pass as `after`.", "type": [ "string", "null" ] } }, "required": [ "stream", "next" ] }, "AuthLogEntry": { "type": "object", "properties": { "time": { "type": [ "string", "null" ], "description": "in the server's time zone, YYYY-MM-DDTHH:MM:SS" }, "ip": { "type": "string", "description": "the client's address" }, "success": { "type": "boolean", "description": "whether the login succeeded" }, "user_agent": { "type": "string" } }, "required": [ "time", "ip", "success", "user_agent" ], "title": "AuthLogEntry" }, "Backup": { "type": "object", "properties": { "name": { "type": "string" }, "user": { "type": "string", "description": "the owner" }, "type": { "type": "string" }, "size_mb": { "type": "integer" }, "created_at": { "type": [ "string", "null" ], "description": "creation time in the server's time zone, YYYY-MM-DDTHH:MM:SS" }, "runtime_seconds": { "type": "integer" }, "content": { "type": "object", "properties": { "web": { "type": "array", "items": { "type": "string" } }, "dns": { "type": "array", "items": { "type": "string" } }, "mail": { "type": "array", "items": { "type": "string" } }, "db": { "type": "array", "items": { "type": "string" } }, "udir": { "type": "array", "items": { "type": "string" } }, "cron": { "type": "boolean" } }, "required": [ "web", "dns", "mail", "db", "udir", "cron" ] } }, "required": [ "name", "user", "type", "size_mb", "created_at", "runtime_seconds", "content" ], "title": "Backup" }, "BackupExclusions": { "type": "object", "properties": { "web": { "type": "array", "items": { "type": "string" } }, "dns": { "type": "array", "items": { "type": "string" } }, "mail": { "type": "array", "items": { "type": "string" } }, "db": { "type": "array", "items": { "type": "string" } }, "cron": { "type": "array", "items": { "type": "string" } }, "user": { "type": "array", "items": { "type": "string" } } }, "required": [ "web", "dns", "mail", "db", "cron", "user" ], "title": "BackupExclusions" }, "BackupsSettings": { "type": "object", "description": "The `backups` tab of the server settings.", "properties": { "directory": { "type": "string", "description": "Read-only." }, "local": { "type": "boolean" }, "mode": { "type": "string" }, "level": { "type": "integer" }, "remote": { "type": "boolean" }, "remote_type": { "type": [ "string", "null" ] }, "host": { "type": [ "string", "null" ] }, "port": { "type": [ "integer", "null" ] }, "username": { "type": [ "string", "null" ] }, "path": { "type": [ "string", "null" ] }, "bucket": { "type": [ "string", "null" ] }, "key_id": { "type": [ "string", "null" ] }, "password": { "$ref": "#/components/schemas/SecretFlag" }, "incremental": { "type": "boolean" }, "repo": { "$ref": "#/components/schemas/SecretFlag" }, "snapshots": { "type": "integer" }, "keep_daily": { "type": "integer" }, "keep_weekly": { "type": "integer" }, "keep_monthly": { "type": "integer" }, "keep_yearly": { "type": "integer" } }, "required": [ "directory", "local", "mode", "level", "remote", "remote_type", "host", "port", "username", "path", "bucket", "key_id", "password", "incremental", "repo", "snapshots", "keep_daily", "keep_weekly", "keep_monthly", "keep_yearly" ] }, "BuildNodeAppRequest": { "type": "object", "properties": { "script": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9:._-]{0,63}$" } }, "title": "BuildNodeAppRequest" }, "ChangeDatabasePasswordRequest": { "type": "object", "description": "PUT /users/{user}/databases/{database}/password.", "properties": { "password": { "type": "string", "pattern": "^(?=.*[a-z])(?=.*[A-Z])(?=.*\\d)(.){8,}$", "maxLength": 256 } }, "required": [ "password" ], "title": "ChangeDatabasePasswordRequest" }, "ChangeFileModeRequest": { "type": "object", "description": "Body of `changeFileMode` (E34 batch 5 spec §4.2).", "properties": { "paths": { "type": "array", "description": "Entries relative to the home directory.", "items": { "type": "string" }, "minItems": 1, "maxItems": 1000, "uniqueItems": true }, "mode": { "type": "string", "description": "Octal mode, e.g. `0644` or `755`.", "pattern": "^[0-7]?[0-7]{3}$" }, "files_mode": { "type": [ "string", "null" ], "description": "With `recursive`: the mode of the files inside a folder (default `mode`).", "pattern": "^[0-7]?[0-7]{3}$" }, "recursive": { "type": "boolean", "description": "A folder: change everything inside too (folders get `mode`, files `files_mode`; symbolic links are skipped). Without it only the folder itself changes." } }, "required": [ "paths", "mode" ], "title": "ChangeFileModeRequest" }, "ChangeMailAccountPasswordRequest": { "type": "object", "description": "PUT /users/{user}/mail-domains/{domain}/accounts/{account}/password.", "properties": { "password": { "type": "string", "pattern": "^(?=.*[a-z])(?=.*[A-Z])(?=.*\\d)(.){8,}$" } }, "required": [ "password" ], "title": "ChangeMailAccountPasswordRequest" }, "ClosePortRuleRequest": { "type": "object", "properties": { "rule": { "type": "integer", "minimum": 1 } }, "required": [ "rule" ], "title": "ClosePortRuleRequest" }, "CompressFilesRequest": { "type": "object", "description": "Body of `compressFiles` (E34 batch 5 spec §4.2).", "properties": { "paths": { "type": "array", "description": "Entries of one folder, relative to the home directory.", "items": { "type": "string" }, "minItems": 1, "maxItems": 1000, "uniqueItems": true }, "name": { "type": "string", "description": "Name of the new zip archive in that folder, ending in `.zip`.", "pattern": "\\.zip$", "maxLength": 255 } }, "required": [ "paths", "name" ], "title": "CompressFilesRequest" }, "CopyPackageRequest": { "type": "object", "description": "POST /packages/{package}/copy", "properties": { "name": { "type": "string", "description": "The name of the copy.", "pattern": "^[[:alnum:]][-.\\w]*$", "maxLength": 60 } }, "required": [ "name" ], "title": "CopyPackageRequest" }, "CreateAccessKeyRequest": { "type": "object", "description": "POST /users/{user}/access-keys (E34 batch 6 §4.6, D62), with the address\nlist and expiry of E43 B6.", "properties": { "permissions": { "type": "array", "description": "Permission sets (see GET /access-key-sets). At least one, except for the own key of an administrator, made with a key without sets: no set gives every command.", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]*$", "maxLength": 64 }, "maxItems": 50, "uniqueItems": true }, "comment": { "type": [ "string", "null" ], "description": "A note for the key, at most 255 characters.", "maxLength": 255 }, "allowed_ips": { "type": [ "array", "null" ], "description": "IPv4 or IPv6 addresses or CIDR networks the key is limited to, at most 20; empty or absent means any address. Set once: a different list means a new key.", "items": { "type": "string", "maxLength": 43 }, "maxItems": 20, "uniqueItems": true }, "expires_at": { "type": [ "string", "null" ], "description": "ISO 8601 time after which the key is refused, at least an hour and at most three years ahead; absent or null means no expiry. Set once.", "maxLength": 40 } }, "required": [ "permissions" ], "title": "CreateAccessKeyRequest" }, "CreateFileRequest": { "type": "object", "description": "Body of `createDirectory` and `createFile` (E34 batch 5 spec §4.2).", "properties": { "path": { "type": [ "string", "null" ], "description": "Parent folder relative to the home directory; the home directory when left out." }, "name": { "type": "string", "description": "Name of the new entry: no slash, not `.` or `..`.", "maxLength": 255 } }, "required": [ "name" ], "title": "CreateFileRequest" }, "CreateUserSecretRequest": { "type": "object", "description": "POST /users/{user}/secrets: a new secret of the secret store (E38).", "properties": { "name": { "type": "string", "description": "A path of one to five parts of letters, digits, `_`, `.` and `-`, for example `/shop/db_password`; at most 128 characters.", "pattern": "^(\\/[A-Za-z0-9_.-]{1,64}){1,5}$", "maxLength": 128 }, "value": { "type": "string", "description": "The value, 1 byte to 32 KiB; it is never returned. One final line break is dropped.", "maxLength": 32768 }, "description": { "type": [ "string", "null" ], "description": "At most 255 characters, without quotes, `$`, backquote, backslash or `|`.", "maxLength": 255 } }, "required": [ "name", "value" ], "title": "CreateUserSecretRequest" }, "CronJob": { "type": "object", "properties": { "id": { "type": "integer" }, "user": { "type": "string", "description": "the owner" }, "schedule": { "type": "string", "description": "five crontab fields" }, "command": { "type": "string" }, "suspended": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ], "description": "creation time in the server's time zone, YYYY-MM-DDTHH:MM:SS" } }, "required": [ "id", "user", "schedule", "command", "suspended", "created_at" ], "title": "CronJob" }, "CrossUserListMeta": { "type": "object", "description": "A page of a cross-user list (E43 B2): `total`, `limit` and `offset` as in `ListMeta`, with the change filter.", "properties": { "total": { "type": "integer", "minimum": 0, "description": "Items before limit and offset." }, "limit": { "type": "integer", "minimum": 1, "maximum": 1000 }, "offset": { "type": "integer", "minimum": 0 }, "as_of": { "type": [ "string", "null" ], "format": "date-time", "description": "Server time (UTC) when the listing started: the next `updated_since`." }, "users": { "type": "array", "items": { "type": "string" }, "description": "Every user in scope; a client drops the users that are no longer listed." }, "changed_users": { "type": "array", "items": { "type": "string" }, "description": "The users whose objects are returned: every user in scope without `updated_since`." }, "timezone": { "type": "string", "description": "The server time zone. Present on listAllCronJobs." } }, "required": [ "total", "as_of", "users", "changed_users" ] }, "Database": { "type": "object", "properties": { "name": { "type": "string", "description": "the full name, with the owner prefix" }, "short_name": { "type": "string", "description": "the name without the owner prefix" }, "user": { "type": "string", "description": "the owner" }, "db_user": { "type": "string", "description": "the full database user name" }, "type": { "type": "string" }, "host": { "type": "string" }, "charset": { "type": "string" }, "disk_mb": { "type": "integer" }, "suspended": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ], "description": "creation time in the server's time zone, YYYY-MM-DDTHH:MM:SS" } }, "required": [ "name", "short_name", "user", "db_user", "type", "host", "charset", "disk_mb", "suspended", "created_at" ], "title": "Database" }, "DatabasesSettings": { "type": "object", "description": "The `databases` tab of the server settings.", "properties": { "db_system": { "type": "string", "description": "Read-only." }, "pma_alias": { "type": [ "string", "null" ] }, "pga_alias": { "type": [ "string", "null" ] }, "db_admin_port": { "type": [ "integer", "null" ] }, "pma_sso": { "type": "boolean", "description": "Read-only through the API (403 on a change)." }, "pma_restrict": { "type": "boolean", "description": "Read-only through the API (403 on a change)." }, "hosts": { "type": "array", "description": "The database hosts; setDatabaseHostPassword changes the password of a MySQL host.", "items": { "type": "object", "properties": { "host": { "type": "string" }, "type": { "type": "string" }, "port": { "type": [ "integer", "null" ] }, "max_databases": { "type": [ "integer", "null" ] }, "databases": { "type": "integer" }, "suspended": { "type": "boolean" } }, "required": [ "host", "type", "port", "max_databases", "databases", "suspended" ] } } }, "required": [ "db_system", "pma_alias", "pga_alias", "db_admin_port", "pma_sso", "pma_restrict", "hosts" ] }, "DeleteFilesRequest": { "type": "object", "description": "Body of `deleteFiles` (E34 batch 5 spec §4.2).", "properties": { "paths": { "type": "array", "description": "Entries relative to the home directory; a folder is deleted with its content.", "items": { "type": "string" }, "minItems": 1, "maxItems": 1000, "uniqueItems": true } }, "required": [ "paths" ], "title": "DeleteFilesRequest" }, "DnsRecord": { "type": "object", "properties": { "id": { "type": [ "integer", "string" ] }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "priority": { "type": [ "integer", "null" ] }, "ttl": { "type": [ "integer", "null" ] }, "suspended": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "type", "value", "priority", "ttl", "suspended", "created_at" ], "title": "DnsRecord" }, "DnsSettings": { "type": "object", "description": "The `dns` tab of the server settings.", "properties": { "dns_system": { "type": "string", "description": "Read-only." }, "dnssec": { "type": "boolean", "description": "Read-only." }, "hosts": { "type": "array", "description": "The DNS cluster hosts (read-only).", "items": { "type": "object", "properties": { "host": { "type": "string" }, "port": { "type": [ "integer", "null" ] }, "type": { "type": "string" }, "user": { "type": "string" }, "dns_user": { "type": "string" }, "suspended": { "type": "boolean" } }, "required": [ "host", "port", "type", "user", "dns_user", "suspended" ] } } }, "required": [ "dns_system", "dnssec", "hosts" ] }, "DnsZone": { "type": "object", "properties": { "domain": { "type": "string" }, "user": { "type": "string" }, "ip": { "type": "string" }, "template": { "type": "string" }, "ttl": { "type": "integer" }, "expiry": { "type": "string" }, "soa": { "type": "string" }, "serial": { "type": [ "integer", "null" ] }, "dnssec": { "type": [ "boolean", "null" ] }, "records": { "type": "integer" }, "suspended": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ] } }, "required": [ "domain", "user", "ip", "template", "ttl", "expiry", "soa", "serial", "dnssec", "records", "suspended", "created_at" ], "title": "DnsZone" }, "DnsZoneDnssec": { "type": "object", "properties": { "domain": { "type": "string" }, "record": { "type": "string" }, "key_tag": { "type": [ "integer", "string" ] }, "flag": { "type": [ "integer", "string" ] }, "algorithm": { "type": [ "integer", "string" ] }, "key": { "type": "string" }, "ds": { "type": "string" } }, "required": [ "domain", "record", "key_tag", "flag", "algorithm", "key", "ds" ], "title": "DnsZoneDnssec" }, "DockerApp": { "type": "object", "description": "One Docker app. Detail fields appear on `getDockerApp` only.", "properties": { "name": { "type": "string" }, "slug": { "type": "string" }, "app_name": { "type": "string" }, "version": { "type": "string" }, "latest_version": { "type": "string" }, "update_available": { "type": "boolean" }, "domain": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "ssl": { "type": "boolean" }, "web_port": { "type": [ "string", "null" ] }, "extra_ports": { "type": [ "string", "null" ] }, "state": { "type": "string" }, "status": { "type": "string" }, "reason": { "type": [ "string", "null" ] }, "suspended": { "type": "boolean" }, "busy": { "type": "boolean" }, "previous_version": { "type": [ "string", "null" ] }, "cpus": { "type": "string" }, "memory_mb": { "type": "integer" }, "cpu": { "type": "number" }, "memory_used_mb": { "type": "integer" }, "containers": { "type": "integer" }, "running_containers": { "type": "integer" }, "created_at": { "type": [ "string", "null" ] }, "services": { "type": "array", "description": "Compose services; present on detail only.", "items": { "$ref": "#/components/schemas/DockerAppServiceEntry" } }, "ports": { "type": "array", "description": "Published ports; present on detail only.", "items": { "$ref": "#/components/schemas/DockerAppPortEntry" } }, "post_install": { "type": [ "string", "null" ], "description": "Post-install note; present on detail only." }, "rollback": { "type": "boolean", "description": "Whether a rollback is available; present on detail only." }, "last_dump": { "type": [ "string", "null" ], "description": "Last database dump path; present on detail only." } }, "required": [ "name", "slug", "app_name", "version", "latest_version", "update_available", "domain", "url", "ssl", "web_port", "extra_ports", "state", "status", "reason", "suspended", "busy", "previous_version", "cpus", "memory_mb", "cpu", "memory_used_mb", "containers", "running_containers", "created_at" ] }, "DockerAppEnvEntry": { "type": "object", "description": "One Docker app environment variable (D42).", "properties": { "name": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string" }, "options": { "type": "array", "items": { "type": "string" } }, "secret": { "type": "boolean" }, "immutable": { "type": "boolean" }, "required": { "type": "boolean" }, "pattern": { "type": "string" }, "set": { "type": "boolean" }, "value": { "type": "string", "description": "Omitted for secrets and generated defaults." } }, "required": [ "name", "label", "type", "secret", "immutable", "required", "set" ] }, "DockerAppListMeta": { "type": "object", "description": "Docker engine state and DOCKER_APPS limits; the app list is not paginated (E34 batch 4 §4.3).", "properties": { "engine": { "type": "boolean", "description": "Whether the Docker engine is installed on the server." }, "totals": { "type": "object", "properties": { "running": { "type": "integer", "minimum": 0 }, "stopped": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 }, "busy": { "type": "integer", "minimum": 0 }, "suspended": { "type": "integer", "minimum": 0 } }, "required": [ "running", "stopped", "failed", "busy", "suspended" ] }, "limit": { "type": "string", "description": "Maximum apps from DOCKER_APPS (`unlimited` or a number)." }, "room": { "type": "boolean", "description": "Whether another app fits under the limit." } }, "required": [ "engine", "totals", "limit", "room" ] }, "DockerAppLogMeta": { "type": "object", "description": "Cursor metadata for Docker log snapshots (D43).", "properties": { "next": { "description": "Cursor for the next snapshot; pass as `after`. Null when there is nothing newer.", "type": [ "string", "null" ] } }, "required": [ "next" ] }, "DockerAppPortEntry": { "type": "object", "properties": { "name": { "type": "string" }, "port": { "type": "string" }, "container": { "type": "string" }, "public": { "type": "boolean" }, "description": { "type": "string" } }, "required": [ "name", "port", "container", "public", "description" ] }, "DockerAppServiceEntry": { "type": "object", "properties": { "service": { "type": "string" }, "image": { "type": "string" }, "state": { "type": "string" }, "health": { "type": "string" }, "status": { "type": "string" } }, "required": [ "service", "image", "state", "health", "status" ] }, "DockerCatalogApp": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "category": { "type": "string" }, "version": { "type": "string" }, "versions": { "type": "array", "items": {} }, "latest_version": { "type": "string" }, "homepage": { "type": [ "string", "null" ] }, "changelog": { "type": [ "string", "null" ] }, "license": { "type": [ "string", "null" ] }, "admin_only": { "type": "boolean" }, "web": { "type": "boolean" }, "requirements": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0 } ] }, "limits": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0 } ] }, "ports": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0 } ] }, "variables": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0 } ] }, "dumps": { "type": "boolean" }, "icon": { "type": [ "string", "null" ] } }, "required": [ "slug", "name", "summary", "description", "category", "version", "versions", "latest_version", "homepage", "changelog", "license", "admin_only", "web", "requirements", "limits", "ports", "variables", "dumps", "icon" ], "title": "DockerCatalogApp" }, "DockerCatalogEntry": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "summary": { "type": "string" }, "category": { "type": "string" }, "version": { "type": "string" }, "versions": { "type": "array", "items": {} }, "admin_only": { "type": "boolean" }, "web": { "type": "boolean" }, "homepage": { "type": [ "string", "null" ] }, "license": { "type": [ "string", "null" ] }, "requirements": { "type": "object", "properties": { "memory": { "type": [ "string", "null" ] }, "disk": { "type": [ "string", "null" ] } }, "required": [ "memory", "disk" ] }, "icon": { "type": [ "string", "null" ] } }, "required": [ "slug", "name", "summary", "category", "version", "versions", "admin_only", "web", "homepage", "license", "requirements", "icon" ], "title": "DockerCatalogEntry" }, "DockerEngine": { "type": "object", "properties": { "installed": { "type": "boolean" }, "running": { "type": "boolean" }, "version": { "type": [ "string", "null" ] }, "compose_version": { "type": [ "string", "null" ] }, "data_root": { "type": [ "string", "null" ] }, "disk_used": { "type": "integer" }, "disk_free": { "type": "integer" }, "images": { "type": "integer" }, "containers": { "type": "integer" }, "apps": { "type": "integer" }, "users": { "type": "integer" }, "report": { "type": "object", "properties": { "time": { "type": [ "string", "null" ] }, "findings": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "string" }, "app": { "type": "string" }, "type": { "type": "string" }, "detail": { "type": "string" }, "repaired": { "type": "boolean" } }, "required": [ "user", "app", "type", "detail", "repaired" ] } } }, "required": [ "time", "findings" ] } }, "required": [ "installed", "running", "version", "compose_version", "data_root", "disk_used", "disk_free", "images", "containers", "apps", "users", "report" ], "title": "DockerEngine" }, "DownloadFilesRequest": { "type": "object", "description": "Body of `downloadFiles` (E34 batch 5 spec §4.4).", "properties": { "paths": { "type": "array", "description": "Entries of one folder, relative to the home directory; not the home directory itself. One file is sent as it is, a folder or several entries as a zip.", "items": { "type": "string" }, "minItems": 1, "maxItems": 1000, "uniqueItems": true }, "inline": { "type": "boolean", "description": "Show one file in the browser when its type allows it (images, audio, video, PDF, plain text; never SVG). Ignored for a zip." } }, "required": [ "paths" ], "title": "DownloadFilesRequest" }, "DryRun": { "type": "object", "properties": { "data": { "type": "object", "properties": { "dry_run": { "type": "boolean", "const": true }, "steps": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "description": "What the step does." }, "command": { "type": "string", "description": "The v-* command of the step." }, "args": { "type": "array", "items": { "type": "string" }, "description": "Arguments of the command; secrets are masked." } }, "required": [ "label", "command", "args" ] } } }, "required": [ "dry_run", "steps" ] } }, "required": [ "data" ] }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "$ref": "#/components/schemas/ErrorCode" }, "message": { "type": "string" }, "fields": { "type": "object", "description": "E_VALIDATION: the messages of each invalid field.", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "commands": { "type": "array", "description": "E_FORBIDDEN by a permission set: the commands the key may not run.", "items": { "type": "string" } }, "existing": { "description": "E_EXISTS when the server can point at the duplicate: its path under /api/v2, or a queued backup or restore task (D21).", "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/Task" } ] }, "step": { "description": "The step of a change that failed.", "anyOf": [ { "$ref": "#/components/schemas/PlanStep" }, { "type": "null" } ] }, "applied": { "type": "array", "description": "The steps that ran before the failed one; they stay applied.", "items": { "$ref": "#/components/schemas/PlanStep" } }, "conflicts": { "type": "array", "description": "E_EXISTS of a file operation: the names that exist in the destination.", "items": { "type": "string" } }, "path": { "type": [ "string", "null" ], "description": "A failed file operation: the path (relative to the home directory) whose step failed." }, "done": { "type": "array", "description": "A failed file operation over several paths: the paths finished before the failure; they stay changed.", "items": { "type": "string" } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "ErrorCode": { "type": "string", "description": "Error names of the command exit codes (func/main.sh) and of the API layer.", "enum": [ "E_UNAUTHENTICATED", "E_API_DISABLED", "E_FORBIDDEN", "E_NOTEXIST", "E_GONE", "E_VALIDATION", "E_RATE_LIMIT", "E_METHOD_NOT_ALLOWED", "E_SERVER", "E_ARGS", "E_INVALID", "E_EXISTS", "E_SUSPENDED", "E_UNSUSPENDED", "E_INUSE", "E_LIMIT", "E_PASSWORD", "E_DISABLED", "E_PARSING", "E_DISK", "E_LA", "E_CONNECT", "E_FTP", "E_DB", "E_RRD", "E_UPDATE", "E_RESTART" ] }, "ExtractArchiveRequest": { "type": "object", "description": "Body of `extractArchive` (E34 batch 5 spec §4.2, D52).", "properties": { "path": { "type": "string", "description": "Archive relative to the home directory: `.zip`, `.tar.gz`, `.tgz`, `.tar.bz2`, `.tbz`, `.tar.zst` or `.7z`.", "pattern": "\\.(zip|tar\\.gz|tgz|tar\\.bz2|tbz|tar\\.zst|7z)$" }, "destination": { "type": "string", "description": "A folder that does not exist yet, relative to the home directory; it is created with its missing parents." } }, "required": [ "path", "destination" ], "title": "ExtractArchiveRequest" }, "FileContent": { "type": "object", "properties": { "path": { "type": "string", "description": "path relative to the home directory" }, "content": { "type": "string", "description": "the text; bytes that are not UTF-8 are replaced (see `utf8`). readFile only" }, "hash": { "type": "string", "description": "SHA-256 of the bytes on disk, in hexadecimal: send it back with saveFile" }, "size": { "type": "integer", "description": "bytes" }, "modified_at": { "type": [ "string", "null" ], "description": "modification time in the server's time zone, YYYY-MM-DDTHH:MM:SS" }, "mime": { "type": [ "string", "null" ], "description": "MIME type" }, "utf8": { "type": "boolean", "description": "false when the file is not valid UTF-8: `content` is scrubbed and saving it back would change the file. readFile only" } }, "required": [ "path", "hash", "size", "modified_at", "mime" ], "title": "FileContent" }, "FileEntry": { "type": "object", "properties": { "name": { "type": "string" }, "path": { "type": "string", "description": "path relative to the home directory; empty for the home directory itself" }, "type": { "type": "string", "enum": [ "file", "directory", "link", "other" ] }, "size": { "type": "integer", "description": "bytes" }, "mode": { "type": "string", "description": "octal mode, e.g. 0644" }, "owner": { "type": "string" }, "group": { "type": "string" }, "modified_at": { "type": [ "string", "null" ], "description": "modification time in the server's time zone, YYYY-MM-DDTHH:MM:SS" }, "link_target": { "type": [ "string", "null" ], "description": "target of a symbolic link" }, "link_type": { "type": [ "string", "null" ], "description": "what a symbolic link points to: folder, file, nothing, other", "enum": [ "d", "f", "missing", "o", null ] }, "link_inside": { "type": "boolean", "description": "whether a symbolic link points inside the home directory; false for other entries" }, "mime": { "type": [ "string", "null" ], "description": "MIME type; null in lists, which do not read it" }, "writable": { "type": [ "boolean", "null" ], "description": "whether the user may write it; null in lists, which do not test it" }, "valid_name": { "type": "boolean", "description": "false for a name the panel cannot address (not UTF-8, control characters): listed, but no operation accepts it" } }, "required": [ "name", "path", "type", "size", "mode", "owner", "group", "modified_at", "link_target", "link_type", "link_inside", "mime", "writable", "valid_name" ], "title": "FileEntry" }, "FileSearchMeta": { "type": "object", "description": "A name search answers at most 500 entries; the list is not paginated (E34 batch 5 §4.1).", "properties": { "truncated": { "type": "boolean", "description": "Whether more than 500 entries matched." } }, "required": [ "truncated" ] }, "FileSearchResult": { "type": "object", "properties": { "name": { "type": "string" }, "path": { "type": "string", "description": "path relative to the home directory" }, "type": { "type": "string", "enum": [ "file", "directory", "link", "other" ] }, "size": { "type": "integer", "description": "bytes" } }, "required": [ "name", "path", "type", "size" ], "title": "FileSearchResult" }, "FinishUploadRequest": { "type": "object", "description": "Body of `finishUpload` (E34 batch 5 spec §4.3).", "properties": { "on_conflict": { "type": "string", "description": "A file that exists at the target: `fail` (default; `409` with `conflicts`), `skip` (the upload is dropped), `overwrite` or `rename` (first free \"name (n).ext\").", "enum": [ "fail", "skip", "overwrite", "rename" ] } }, "title": "FinishUploadRequest" }, "FirewallBan": { "type": "object", "properties": { "ip": { "type": "string", "description": "an address or a network; URL-encode it in paths" }, "chain": { "type": "string", "enum": [ "SSH", "WEB", "FTP", "DNS", "MAIL", "DB", "ARCPANEL" ] }, "created_at": { "type": [ "string", "null" ], "description": "when the address was banned, in the server's time zone" } }, "required": [ "ip", "chain", "created_at" ], "title": "FirewallBan" }, "FirewallIpset": { "type": "object", "properties": { "name": { "type": "string" }, "source": { "type": "string", "description": "a URL, `script:PATH` or a file" }, "ip_version": { "type": "string", "enum": [ "v4", "v6" ] }, "auto_update": { "type": "boolean" }, "suspended": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ], "description": "in the server's time zone, YYYY-MM-DDTHH:MM:SS" } }, "required": [ "name", "source", "ip_version", "auto_update", "suspended", "created_at" ], "title": "FirewallIpset" }, "FirewallRule": { "type": "object", "properties": { "id": { "type": "integer", "description": "the position of the rule; rules apply in this order" }, "action": { "type": "string", "enum": [ "ACCEPT", "DROP" ] }, "protocol": { "type": "string", "enum": [ "TCP", "UDP", "ICMP" ] }, "port": { "type": "string", "description": "a port, a range or a list; `0` is every port" }, "source": { "type": "string", "description": "an address, a network, or `ipset:NAME`" }, "comment": { "type": [ "string", "null" ] }, "suspended": { "type": "boolean" }, "managed": { "type": "boolean", "description": "the port registry's rule (comment `arcpanel-port-…`): it can be read and moved, not changed" }, "updated_at": { "type": [ "string", "null" ], "description": "when the rule was last written (created, changed or moved), in the server's time zone" } }, "required": [ "id", "action", "protocol", "port", "source", "comment", "suspended", "managed", "updated_at" ], "title": "FirewallRule" }, "GeneralSettings": { "type": "object", "description": "The `general` tab of the server settings.", "properties": { "hostname": { "type": "string" }, "timezone": { "type": "string" }, "language": { "type": "string" }, "theme": { "type": "string" }, "user_theme": { "type": "boolean" }, "debug": { "type": "boolean" }, "experimental": { "type": "boolean" }, "version": { "type": "string", "description": "Read-only." }, "release_branch": { "type": "string", "description": "Read-only." } }, "required": [ "hostname", "timezone", "language", "theme", "user_theme", "debug", "experimental", "version", "release_branch" ] }, "GivePortsRequest": { "type": "object", "properties": { "to": { "type": "string", "pattern": "^[[:alnum:]][-.\\w]{0,28}[[:alnum:]]$" }, "range": { "type": [ "string", "null" ], "pattern": "^\\d{1,5}(-\\d{1,5})?$" }, "count": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 10000 } }, "required": [ "to" ], "title": "GivePortsRequest" }, "Graph": { "type": "object", "properties": { "id": { "type": "string", "description": "the id getGraph takes, for example `la`, `mem` or `net_eth0`" }, "title": { "type": "string" }, "type": { "type": "string", "description": "the kind of graph, for example `la`, `mem`, `net`, `web` or `db`" } }, "required": [ "id", "title", "type" ], "title": "Graph" }, "GraphData": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "period": { "type": "string", "description": "`daily`, `weekly`, `monthly`, `yearly`, `biennially` or `triennially`" }, "unit": { "type": [ "string", "null" ], "description": "the unit of the values, for example `Connections` or `KBytes`" }, "start": { "type": "integer", "description": "the first point, in seconds since the Unix epoch" }, "end": { "type": "integer", "description": "the end of the period, in seconds since the Unix epoch" }, "step": { "type": "integer", "description": "seconds between two points" }, "series": { "type": "array", "description": "the names of the series, in the order of `values`", "items": { "type": "string" } }, "points": { "type": "array", "description": "`time` in seconds since the Unix epoch; one value per series", "items": { "type": "object", "properties": { "time": { "type": "integer" }, "values": { "type": "array", "items": { "type": [ "number", "null" ] } } }, "required": [ "time", "values" ] } } }, "required": [ "id", "title", "period", "unit", "start", "end", "step", "series", "points" ], "title": "GraphData" }, "InstallNodePackageRequest": { "type": "object", "description": "POST /users/{user}/node/versions/{version}/packages", "properties": { "spec": { "type": "string", "pattern": "^(@[a-z0-9][a-z0-9._~-]*\\/)?[a-z0-9][a-z0-9._~-]*(@[A-Za-z0-9.^~<>=*+-]{1,64})?$", "maxLength": 280 } }, "required": [ "spec" ], "title": "InstallNodePackageRequest" }, "InstallNodeVersionRequest": { "type": "object", "description": "POST /users/{user}/node/versions", "properties": { "spec": { "type": "string", "pattern": "^(lts|\\d{1,3}|\\d{1,3}\\.\\d{1,3}\\.\\d{1,3})$" } }, "required": [ "spec" ], "title": "InstallNodeVersionRequest" }, "Ip": { "type": "object", "properties": { "ip": { "type": "string", "description": "the address; URL-encode it in paths where needed" }, "netmask": { "type": "string" }, "interface": { "type": "string", "description": "the network interface" }, "shared": { "type": "boolean", "description": "shared by every account, or dedicated to `owner`" }, "owner": { "type": "string" }, "name": { "type": [ "string", "null" ], "description": "the assigned domain" }, "nat": { "type": [ "string", "null" ], "description": "the public address in front of this one" }, "web_domains": { "type": "integer", "description": "web domains on the address" }, "users": { "type": "array", "description": "accounts that use the address", "items": { "type": "string" } }, "created_at": { "type": [ "string", "null" ], "description": "creation time in the server's time zone, YYYY-MM-DDTHH:MM:SS" } }, "required": [ "ip", "netmask", "interface", "shared", "owner", "name", "nat", "web_domains", "users", "created_at" ], "title": "Ip" }, "LetsEncryptRequest": { "type": "object", "description": "POST /users/{user}/web-domains/{domain}/letsencrypt.", "properties": { "key_algorithm": { "type": "string", "description": "The key type of the certificate; the domain's current one when left out.", "enum": [ "ecdsa-256", "ecdsa-384", "rsa" ] } }, "title": "LetsEncryptRequest" }, "ListMeta": { "type": "object", "description": "Without `limit` only `total` is present and `data` is the full list. With `limit`, `offset` is present too (0 when the client omits it) and `data` is that page.", "properties": { "total": { "type": "integer", "minimum": 0, "description": "Items before limit and offset." }, "limit": { "type": "integer", "minimum": 1, "maximum": 1000 }, "offset": { "type": "integer", "minimum": 0 }, "timezone": { "type": "string", "description": "The server time zone. Present on listCronJobs." } }, "required": [ "total" ] }, "LogEntry": { "type": "object", "properties": { "time": { "type": [ "string", "null" ], "description": "in the server's time zone, YYYY-MM-DDTHH:MM:SS" }, "level": { "type": "string", "description": "`Info`, `Warning` or `Error`" }, "category": { "type": "string", "description": "the area of the panel, for example `Web` or `System`" }, "message": { "type": "string", "description": "plain text as the command logged it" } }, "required": [ "time", "level", "category", "message" ], "title": "LogEntry" }, "LogListMeta": { "type": "object", "description": "A page of the newest log entries (E34 batch 6 D60): `limit` (default 100) entries after `offset` newer ones.", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 1000 }, "offset": { "type": "integer", "minimum": 0, "maximum": 8999 }, "more": { "type": "boolean", "description": "Whether older entries exist after this page." } }, "required": [ "limit", "offset", "more" ] }, "MailAccount": { "type": "object", "properties": { "account": { "type": "string", "description": "the local part" }, "address": { "type": "string", "description": "account@domain" }, "aliases": { "type": "array", "items": { "type": "string" } }, "forwards": { "type": "array", "description": "addresses, without the discard marker", "items": { "type": "string" } }, "forward_only": { "type": "boolean", "description": "incoming mail is not stored" }, "discard_all": { "type": "boolean", "description": "mail is discarded" }, "autoreply": { "type": [ "string", "null" ], "description": "the autoreply text, null when it is off" }, "quota_mb": { "type": [ "integer", "null" ], "description": "megabytes, null when unlimited" }, "rate_limit": { "type": [ "integer", "null" ], "description": "messages per hour, null for the system default" }, "disk_mb": { "type": "integer" }, "suspended": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ], "description": "creation time in the server's time zone, YYYY-MM-DDTHH:MM:SS" } }, "required": [ "account", "address", "aliases", "forwards", "forward_only", "discard_all", "autoreply", "quota_mb", "rate_limit", "disk_mb", "suspended", "created_at" ], "title": "MailAccount" }, "MailDnsRecord": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "priority": { "type": [ "integer", "null" ], "description": "null for a record type without a priority" } }, "required": [ "name", "type", "value", "priority" ], "title": "MailDnsRecord" }, "MailDomain": { "type": "object", "properties": { "domain": { "type": "string" }, "user": { "type": "string", "description": "the owner" }, "antispam": { "type": "boolean" }, "antivirus": { "type": "boolean" }, "dkim": { "type": "boolean" }, "reject": { "type": "boolean" }, "catchall": { "type": [ "string", "null" ], "description": "the address that receives mail for unknown accounts" }, "webmail": { "type": [ "string", "null" ], "description": "the webmail client, null when webmail is off" }, "rate_limit": { "type": [ "integer", "null" ], "description": "messages per hour, null for the system default" }, "ssl": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "letsencrypt": { "type": "boolean", "description": "the certificate comes from Let's Encrypt" }, "key_algorithm": { "type": [ "string", "null" ], "description": "the stored key type", "enum": [ "ecdsa-256", "ecdsa-384", "rsa", null ] }, "certificate": { "type": [ "object", "null" ], "description": "The installed certificate, null without SSL; only part of a single domain.", "properties": { "subject": { "type": "string" }, "names": { "type": "array", "description": "the names it covers", "items": { "type": "string" } }, "issuer": { "type": "string" }, "not_before": { "type": [ "string", "null" ], "description": "start of validity, UTC, YYYY-MM-DDTHH:MM:SSZ" }, "not_after": { "type": [ "string", "null" ], "description": "end of validity, UTC, YYYY-MM-DDTHH:MM:SSZ" } }, "required": [ "subject", "names", "issuer", "not_before", "not_after" ] } }, "required": [ "enabled", "letsencrypt", "key_algorithm" ] }, "smtp_relay": { "type": [ "object", "null" ], "description": "The SMTP relay, null when the domain sends mail itself. The password is never returned.", "properties": { "host": { "type": "string" }, "port": { "type": [ "integer", "null" ] }, "username": { "type": "string" } }, "required": [ "host", "port", "username" ] }, "accounts": { "type": "integer" }, "disk_mb": { "type": "integer" }, "suspended": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ], "description": "creation time in the server's time zone, YYYY-MM-DDTHH:MM:SS" } }, "required": [ "domain", "user", "antispam", "antivirus", "dkim", "reject", "catchall", "webmail", "rate_limit", "ssl", "smtp_relay", "accounts", "disk_mb", "suspended", "created_at" ], "title": "MailDomain" }, "MailSettings": { "type": "object", "description": "The `mail` tab of the server settings.", "properties": { "mail_system": { "type": "string", "description": "Read-only." }, "imap_system": { "type": [ "string", "null" ], "description": "Read-only." }, "antivirus_system": { "type": [ "string", "null" ], "description": "Read-only." }, "antispam_system": { "type": [ "string", "null" ], "description": "Read-only." }, "webmail_system": { "type": [ "string", "null" ], "description": "Read-only." }, "webmail_alias": { "type": [ "string", "null" ] }, "webmail_port": { "type": [ "integer", "null" ] }, "webmail_link": { "type": [ "string", "null" ] }, "relay": { "type": "boolean" }, "relay_host": { "type": [ "string", "null" ] }, "relay_port": { "type": [ "integer", "null" ] }, "relay_user": { "type": [ "string", "null" ] }, "relay_password": { "$ref": "#/components/schemas/SecretFlag" } }, "required": [ "mail_system", "imap_system", "antivirus_system", "antispam_system", "webmail_system", "webmail_alias", "webmail_port", "webmail_link", "relay", "relay_host", "relay_port", "relay_user", "relay_password" ] }, "MalwareFinding": { "type": "object", "properties": { "id": { "type": "string", "description": "16 hex characters, stable across scans of the same file" }, "domain": { "type": "string" }, "path": { "type": "string", "description": "relative to the domain's public_html" }, "sha256": { "type": "string" }, "size": { "type": "integer", "description": "bytes" }, "modified_at": { "type": [ "string", "null" ], "description": "modification time of the file when it was scanned, server time" }, "severity": { "type": "string", "description": "critical, high or medium: the most severe of the rules" }, "rules": { "type": "array", "description": "ids of the rules that matched", "items": { "type": "string" } }, "descriptions": { "type": "array", "description": "what each rule detects, in the order of `rules`", "items": { "type": "string" } }, "line": { "type": "integer", "description": "the line of the most severe match" }, "snippet": { "type": "string", "description": "that line, at most 200 characters, control characters replaced" }, "detected_at": { "type": [ "string", "null" ], "description": "first reported, server time" }, "scan_id": { "type": "string", "description": "the scan that reported the current content" } }, "required": [ "id", "domain", "path", "sha256", "size", "modified_at", "severity", "rules", "descriptions", "line", "snippet", "detected_at", "scan_id" ], "title": "MalwareFinding" }, "MalwareIgnore": { "type": "object", "properties": { "sha256": { "type": "string" }, "domain": { "type": "string", "description": "the domain of the finding that was marked" }, "path": { "type": "string", "description": "the path of the finding that was marked" }, "rules": { "type": "array", "items": { "type": "string" } }, "added_at": { "type": [ "string", "null" ], "description": "server time" } }, "required": [ "sha256", "domain", "path", "rules", "added_at" ], "title": "MalwareIgnore" }, "MalwareQuarantine": { "type": "object", "properties": { "id": { "type": "string", "description": "14 digits" }, "domain": { "type": "string" }, "path": { "type": "string", "description": "where the file goes back on restore, relative to public_html" }, "sha256": { "type": "string" }, "size": { "type": "integer", "description": "bytes" }, "mode": { "type": "string", "description": "octal permissions it gets back on restore, for example `644`" }, "severity": { "type": "string", "description": "critical, high or medium" }, "rules": { "type": "array", "items": { "type": "string" } }, "quarantined_at": { "type": [ "string", "null" ], "description": "server time" } }, "required": [ "id", "domain", "path", "sha256", "size", "mode", "severity", "rules", "quarantined_at" ], "title": "MalwareQuarantine" }, "MalwareScan": { "type": "object", "properties": { "id": { "type": "string", "description": "14 digits" }, "domain": { "type": [ "string", "null" ], "description": "null when every web domain of the user was scanned" }, "mode": { "type": "string", "description": "full or incremental (only new and changed files)" }, "trigger": { "type": "string", "description": "manual or nightly" }, "status": { "type": "string", "description": "running, done or failed" }, "started_at": { "type": [ "string", "null" ], "description": "server time" }, "finished_at": { "type": [ "string", "null" ], "description": "server time" }, "files": { "type": "integer", "description": "candidate files" }, "changed": { "type": "integer", "description": "files read (the others were unchanged since the last scan)" }, "skipped": { "type": "integer", "description": "files above 2 MiB, not read" }, "errors": { "type": "integer", "description": "files the user cannot read" }, "findings": { "type": "integer", "description": "open findings of the scanned domains after the scan" }, "new": { "type": "integer", "description": "findings not reported before" }, "new_summary": { "type": "array", "description": "new findings per domain", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "critical": { "type": "integer" }, "high": { "type": "integer" }, "medium": { "type": "integer" } }, "required": [ "domain", "critical", "high", "medium" ] } }, "rules_version": { "type": "string", "description": "version of the rules" }, "error": { "type": [ "string", "null" ], "description": "domains that could not be scanned, and why" } }, "required": [ "id", "domain", "mode", "trigger", "status", "started_at", "finished_at", "files", "changed", "skipped", "errors", "findings", "new", "new_summary", "rules_version", "error" ], "title": "MalwareScan" }, "MalwareSummary": { "type": "object", "properties": { "user": { "type": "string" }, "findings": { "type": "integer", "description": "open findings" }, "critical": { "type": "integer" }, "high": { "type": "integer" }, "medium": { "type": "integer" }, "quarantined": { "type": "integer" }, "last_scan_at": { "type": [ "string", "null" ], "description": "start of the newest scan, server time; null when never scanned" }, "last_status": { "type": [ "string", "null" ], "description": "running, done or failed" } }, "required": [ "user", "findings", "critical", "high", "medium", "quarantined", "last_scan_at", "last_status" ], "title": "MalwareSummary" }, "Me": { "type": "object", "properties": { "access_key_id": { "type": "string", "description": "the access key id" }, "user": { "type": "string", "description": "the owner of the key; every call acts as this user" }, "role": { "$ref": "#/components/schemas/ApiRole" }, "read_only": { "type": "boolean", "description": "whether the user may only read (no write endpoint answers)" }, "permissions": { "type": "array", "items": { "type": "string" } }, "commands": { "type": "array", "description": "the commands the key may run, `*` when unrestricted", "items": { "type": "string" } }, "panel_version": { "type": "string" }, "api_version": { "type": "string" }, "server_id": { "type": "string", "description": "the server's identifier (SERVER_ID), the same for every key of the server (E43 B1)" }, "key_expires_at": { "type": [ "string", "null" ], "description": "ISO 8601 expiry of the calling key, null without one" }, "key_allowed_ips": { "type": "array", "description": "addresses and networks the calling key is limited to; empty when unrestricted", "items": { "type": "string" } } }, "required": [ "access_key_id", "user", "role", "read_only", "permissions", "commands", "panel_version", "api_version", "server_id", "key_expires_at", "key_allowed_ips" ], "title": "Me" }, "MoveFirewallRuleRequest": { "type": "object", "description": "POST /system/firewall/rules/{rule}/move (E34 batch 6 spec D59).", "properties": { "direction": { "type": "string", "description": "`up` swaps the rule with the one before it, `down` with the one after it.", "enum": [ "up", "down" ] } }, "required": [ "direction" ], "title": "MoveFirewallRuleRequest" }, "NetworkInterface": { "type": "object", "properties": { "name": { "type": "string", "description": "for example `eth0`" } }, "required": [ "name" ], "title": "NetworkInterface" }, "NewAccessKey": { "type": "object", "properties": { "id": { "type": "string", "description": "the access key id, 20 letters and digits" }, "permissions": { "type": "array", "items": { "type": "string" } }, "comment": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "description": "in the server's time zone, YYYY-MM-DDTHH:MM:SS" }, "allowed_ips": { "type": "array", "description": "addresses and networks the key is limited to; empty when unrestricted (E43 B6)", "items": { "type": "string" } }, "expires_at": { "type": [ "string", "null" ], "description": "ISO 8601 time in UTC after which the key is refused; null without an expiry" }, "secret": { "type": "string", "description": "the secret access key; shown only here. Authenticate with `Authorization: Bearer ID:SECRET`." } }, "required": [ "id", "permissions", "comment", "created_at", "allowed_ips", "expires_at", "secret" ], "title": "NewAccessKey" }, "NodeAccount": { "type": "object", "properties": { "enabled": { "type": "string" }, "default_version": { "type": [ "string", "null" ] }, "allowed_versions": { "type": "string" }, "limit": { "type": "string" }, "room": { "type": "string" }, "runtimes": { "type": "array", "items": { "$ref": "#/components/schemas/NodeRuntime" } } }, "required": [ "enabled", "default_version", "allowed_versions", "limit", "room", "runtimes" ], "title": "NodeAccount" }, "NodeApp": { "type": "object", "properties": { "domain": { "type": "string" }, "user": { "type": "string", "description": "the owner" }, "name": { "type": "string" }, "start": { "type": "string" }, "script": { "type": "string" }, "cwd": { "type": "string" }, "node_version": { "type": "string" }, "runtime": { "type": [ "string", "null" ], "description": "the installed version the app runs with; null in listAllNodeApps" }, "port": { "type": "string" }, "instances": { "type": "string" }, "max_memory_mb": { "type": "string" }, "template": { "type": "string" }, "state": { "type": "string" }, "status": { "type": [ "string", "null" ], "description": "the live state of pm2; null in listAllNodeApps, which reads only the records" }, "online": { "type": [ "boolean", "null" ] }, "reason": { "type": [ "string", "null" ] }, "pid": { "type": [ "string", "null" ] }, "cpu": { "type": [ "number", "null" ] }, "memory_mb": { "type": [ "integer", "null" ] }, "restarts": { "type": [ "integer", "null" ] }, "uptime_seconds": { "type": [ "integer", "null" ] }, "url": { "type": "string" }, "ssl": { "type": "string" }, "suspended": { "type": "string" }, "created_at": { "type": [ "string", "null" ] } }, "required": [ "domain", "user", "name", "start", "script", "cwd", "node_version", "runtime", "port", "instances", "max_memory_mb", "template", "state", "status", "online", "reason", "pid", "cpu", "memory_mb", "restarts", "uptime_seconds", "url", "ssl", "suspended", "created_at" ], "title": "NodeApp" }, "NodeAppEnvEntry": { "type": "object", "description": "One environment variable (D41).", "properties": { "name": { "type": "string" }, "set": { "type": "boolean", "description": "Whether a non-empty value is stored." }, "value": { "type": "string", "description": "Present only when `reveal=1` and the key holds `v2-apps` or `v2-write`." } }, "required": [ "name", "set" ] }, "NodeAppListMeta": { "type": "object", "description": "The user's pm2 daemon and NODE_APPS limits; the app list is not paginated (E34 batch 4 §4.2).", "properties": { "daemon": { "type": "boolean", "description": "Whether the user's pm2 daemon is running." }, "totals": { "type": "object", "properties": { "online": { "type": "integer", "minimum": 0 }, "stopped": { "type": "integer", "minimum": 0 }, "errored": { "type": "integer", "minimum": 0 }, "suspended": { "type": "integer", "minimum": 0 } }, "required": [ "online", "stopped", "errored", "suspended" ] }, "limit": { "type": "string", "description": "Maximum apps from NODE_APPS (`unlimited` or a number)." }, "room": { "type": "boolean", "description": "Whether another app fits under the limit." } }, "required": [ "daemon", "totals", "limit", "room" ] }, "NodeAppLogMeta": { "type": "object", "description": "Cursor metadata for log snapshots (D43).", "properties": { "stream": { "type": "string", "enum": [ "out", "err", "install", "build" ] }, "next": { "description": "Cursor for the next snapshot; pass as `after`. Null when there is nothing newer.", "type": [ "string", "null" ] } }, "required": [ "stream", "next" ] }, "NodePackage": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "latest": { "type": [ "string", "null" ] }, "outdated": { "type": "boolean" }, "bundled": { "type": "string" } }, "required": [ "name", "version", "latest", "outdated", "bundled" ], "title": "NodePackage" }, "NodeRelease": { "type": "object", "properties": { "major": { "type": "string" }, "latest": { "type": "string" }, "lts": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "eol": { "type": [ "string", "null" ] }, "cached": { "type": "string" }, "allowed": { "type": "string" } }, "required": [ "major", "latest", "lts", "status", "eol", "cached", "allowed" ], "title": "NodeRelease" }, "NodeRuntime": { "type": "object", "properties": { "version": { "type": "string" }, "major": { "type": "string" }, "default": { "type": "string" }, "lts": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "eol": { "type": [ "string", "null" ] }, "size_mb": { "type": "string" }, "packages": { "type": "string" } }, "required": [ "version", "major", "default", "lts", "status", "eol", "size_mb", "packages" ], "title": "NodeRuntime" }, "Notification": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string", "description": "plain text" }, "body": { "type": "string", "description": "plain text; links of the notice are dropped" }, "acknowledged": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ], "description": "in the server's time zone, YYYY-MM-DDTHH:MM:SS" } }, "required": [ "id", "title", "body", "acknowledged", "created_at" ], "title": "Notification" }, "Package": { "type": "object", "properties": { "name": { "type": "string", "description": "the name in paths; a reseller's own packages are stored as RESELLER_NAME" }, "label": { "type": "string", "description": "the name as its owner sees it" }, "owner": { "type": [ "string", "null" ], "description": "the reseller that created the package; null for the administrator's" }, "users": { "type": "integer", "description": "users on the package" }, "templates": { "type": "object", "properties": { "web": { "type": "string" }, "backend": { "type": "string" }, "proxy": { "type": "string" }, "dns": { "type": "string" } }, "required": [ "web", "backend", "proxy", "dns" ] }, "limits": { "type": "object", "properties": { "web_domains": { "type": [ "integer", "null" ] }, "web_aliases": { "type": [ "integer", "null" ] }, "dns_domains": { "type": [ "integer", "null" ] }, "dns_records": { "type": [ "integer", "null" ] }, "mail_domains": { "type": [ "integer", "null" ] }, "mail_accounts": { "type": [ "integer", "null" ] }, "databases": { "type": [ "integer", "null" ] }, "cron_jobs": { "type": [ "integer", "null" ] }, "disk_mb": { "type": [ "integer", "null" ] }, "bandwidth_mb": { "type": [ "integer", "null" ] }, "rate_limit": { "type": "integer", "description": "outgoing mails an hour per account" }, "backups": { "type": "integer", "description": "backups kept" } }, "required": [ "web_domains", "web_aliases", "dns_domains", "dns_records", "mail_domains", "mail_accounts", "databases", "cron_jobs", "disk_mb", "bandwidth_mb", "rate_limit", "backups" ] }, "resources": { "type": "object", "description": "cgroup limits, applied when the server has RESOURCES_LIMIT='yes' (values such as 50%, 100ms, 512M)", "properties": { "cpu_quota": { "type": [ "string", "null" ] }, "cpu_quota_period": { "type": [ "string", "null" ] }, "memory_limit": { "type": [ "string", "null" ] }, "swap_limit": { "type": [ "string", "null" ] } }, "required": [ "cpu_quota", "cpu_quota_period", "memory_limit", "swap_limit" ] }, "shell": { "type": "string" }, "nameservers": { "type": "array", "items": { "type": "string" } }, "backups_incremental": { "type": "boolean" }, "reseller": { "type": "object", "description": "What a reseller on this package may do (E11)", "properties": { "users": { "type": [ "integer", "null" ], "description": "customers a reseller on this package may have" }, "packages": { "type": "array", "description": "packages it may assign, `*` for every visible one", "items": { "type": "string" } }, "visible": { "type": "boolean", "description": "whether resellers may assign this package" } }, "required": [ "users", "packages", "visible" ] }, "ports": { "type": [ "integer", "null" ], "description": "ports of the port registry (E12)" }, "node": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "versions": { "type": [ "integer", "null" ], "description": "runtimes per user" }, "allowed": { "type": "string", "description": "`lts`, `*` or a list of major versions" }, "apps": { "type": [ "integer", "null" ], "description": "apps per user" } }, "required": [ "enabled", "versions", "allowed", "apps" ] }, "docker": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "apps": { "type": [ "integer", "null" ], "description": "apps per user" }, "cpus": { "type": [ "string", "null" ], "description": "CPUs per app" }, "memory": { "type": [ "string", "null" ], "description": "memory per app (512M, 2G)" } }, "required": [ "enabled", "apps", "cpus", "memory" ] }, "app_processes": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "app processes allowed (E42)" }, "max": { "type": [ "integer", "null" ], "description": "processes per user" }, "memory": { "type": [ "string", "null" ], "description": "memory per process (512M, 1G)" }, "cpus": { "type": [ "string", "null" ], "description": "CPUs per process" } }, "required": [ "enabled", "max", "memory", "cpus" ] }, "php": { "type": "object", "properties": { "versions": { "type": "string", "description": "`*` (every installed version that has not reached its end of life) or a comma list of versions (E41)" }, "profiles": { "type": "string", "description": "`*` or a comma list of PHP-FPM profiles" }, "default_profile": { "type": "string", "description": "the profile of new web domains" } }, "required": [ "versions", "profiles", "default_profile" ] }, "created_at": { "type": [ "string", "null" ], "description": "creation time in the server's time zone, YYYY-MM-DDTHH:MM:SS" } }, "required": [ "name", "label", "owner", "users", "templates", "limits", "resources", "shell", "nameservers", "backups_incremental", "reseller", "ports", "node", "docker", "app_processes", "php", "created_at" ], "title": "Package" }, "PanelPackage": { "type": "object", "properties": { "name": { "type": "string", "description": "`arcpanel`, `arcpanel-nginx` or `arcpanel-php`; runUpdates takes it as `package`" }, "version": { "type": "string", "description": "the installed version" }, "arch": { "type": "string" }, "description": { "type": "string" }, "up_to_date": { "type": "boolean", "description": "false when the archive has a newer version" }, "built_at": { "type": [ "string", "null" ], "description": "when the installed version was built" } }, "required": [ "name", "version", "arch", "description", "up_to_date", "built_at" ], "title": "PanelPackage" }, "PhpExtension": { "type": "object", "properties": { "name": { "type": "string", "description": "the name the paths take, for example `redis`" }, "module": { "type": "string", "description": "the module name of phpenmod" }, "package": { "type": [ "string", "null" ], "description": "the Debian package; null for a module that ships with PHP (on and off only)" }, "group": { "type": "string", "description": "`cache`, `database`, `image`, `format`, `network`, `security`, `async`, `debug` or `other`" }, "required": { "type": "boolean", "description": "required modules cannot be removed or turned off" }, "conflicts": { "type": "array", "description": "extensions that cannot be enabled at the same time", "items": { "type": "string" } }, "note": { "type": [ "string", "null" ], "description": "a warning, for example for xdebug" }, "catalog": { "type": "boolean", "description": "false for a module of the server that the panel does not manage" }, "installed": { "type": "boolean" }, "available": { "type": "boolean", "description": "whether it can be installed for this version" }, "fpm": { "type": "boolean", "description": "enabled for PHP-FPM" }, "cli": { "type": "boolean", "description": "enabled for the command line" } }, "required": [ "name", "module", "package", "group", "required", "conflicts", "note", "catalog", "installed", "available", "fpm", "cli" ], "title": "PhpExtension" }, "PhpIni": { "type": "object", "properties": { "version": { "type": "string" }, "sapi": { "type": "string", "description": "`fpm` or `cli`" }, "file": { "type": "string", "description": "the path of the file" }, "size": { "type": "integer", "description": "bytes" }, "modified_at": { "type": [ "string", "null" ], "description": "`YYYY-MM-DD HH:MM:SS`" }, "values": { "type": "object", "description": "The directives of the form: value, source (`file` or `default`,\nPHP's built-in value), line in the file, and the number of web\ndomains whose profile sets their own value (PHP-FPM only).", "additionalProperties": { "type": "object", "properties": { "value": { "type": "string" }, "source": { "type": "string" }, "line": { "type": [ "integer", "null" ] }, "profile_overrides": { "type": "integer" } }, "required": [ "value", "source", "line", "profile_overrides" ] } }, "content": { "type": [ "string", "null" ], "description": "the file itself, with `?raw=1`" }, "findings": { "type": "array", "description": "warnings of the saved file", "items": { "type": "object", "properties": { "line": { "type": "integer" }, "level": { "type": "string" }, "directive": { "type": "string" }, "message": { "type": "string" } }, "required": [ "line", "level", "directive", "message" ] } } }, "required": [ "version", "sapi", "file", "size", "modified_at", "values" ], "title": "PhpIni" }, "PhpIniBackup": { "type": "object", "properties": { "id": { "type": "string", "description": "the id the restore path takes, `YYYYmmdd-HHMMSS`" }, "created_at": { "type": "string", "description": "`YYYY-MM-DD HH:MM:SS`" }, "size": { "type": "integer", "description": "bytes" } }, "required": [ "id", "created_at", "size" ], "title": "PhpIniBackup" }, "PhpProfile": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "pm": { "type": "string", "description": "`ondemand`, `dynamic` or `static`" }, "max_children": { "type": "integer", "description": "pm.max_children" }, "start_servers": { "type": [ "integer", "null" ], "description": "pm.start_servers (dynamic)" }, "min_spare": { "type": [ "integer", "null" ], "description": "pm.min_spare_servers (dynamic)" }, "max_spare": { "type": [ "integer", "null" ], "description": "pm.max_spare_servers (dynamic)" }, "max_requests": { "type": "integer", "description": "pm.max_requests; 0 never recycles a process" }, "idle_timeout": { "type": [ "string", "null" ], "description": "pm.process_idle_timeout (ondemand), for example `10s`" }, "request_terminate_timeout": { "type": [ "string", "null" ], "description": "request_terminate_timeout, for example `300s`" }, "limits": { "type": "object", "description": "PHP limits written as php_admin_value; null takes the value of php.ini.", "properties": { "memory_limit": { "type": [ "string", "null" ] }, "upload_max_filesize": { "type": [ "string", "null" ] }, "post_max_size": { "type": [ "string", "null" ] }, "max_execution_time": { "type": [ "integer", "null" ] }, "max_input_vars": { "type": [ "integer", "null" ] } }, "required": [ "memory_limit", "upload_max_filesize", "post_max_size", "max_execution_time", "max_input_vars" ] }, "builtin": { "type": "boolean", "description": "one of the shipped profiles; `default` cannot be deleted" }, "domains": { "type": "integer", "description": "web domain pools that use it" }, "packages": { "type": "array", "description": "packages that allow it", "items": { "type": "string" } } }, "required": [ "name", "description", "pm", "max_children", "start_servers", "min_spare", "max_spare", "max_requests", "idle_timeout", "request_terminate_timeout", "limits", "builtin", "domains", "packages" ], "title": "PhpProfile" }, "PhpProfileRequest": { "type": "object", "description": "POST /system/php/profiles and PUT /system/php/profiles/{name} (E41 §7.1).\nThe shape is checked here; the command checks the relations (spare\nservers, upload limits) and answers with the first error.", "properties": { "name": { "type": "string", "description": "Lower-case letters, digits and `-`, up to 32 characters. Only when creating.", "pattern": "^[a-z0-9][a-z0-9-]{0,31}$" }, "description": { "type": [ "string", "null" ], "maxLength": 100 }, "pm": { "type": "string", "description": "`ondemand`, `dynamic` or `static`.", "enum": [ "ondemand", "dynamic", "static" ] }, "max_children": { "type": "integer", "minimum": 1, "maximum": 500 }, "start_servers": { "type": [ "integer", "null" ], "description": "Dynamic only: min_spare ≤ start_servers ≤ max_spare ≤ max_children.", "minimum": 1, "maximum": 500 }, "min_spare": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 500 }, "max_spare": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 500 }, "max_requests": { "type": "integer", "description": "0 never recycles a process.", "minimum": 0, "maximum": 100000 }, "idle_timeout": { "type": [ "string", "null" ], "description": "Ondemand only, for example `10s`.", "pattern": "^\\d{1,5}s$" }, "request_terminate_timeout": { "type": [ "string", "null" ], "description": "For example `300s`; null for none.", "pattern": "^\\d{1,5}s$" }, "limits": { "type": [ "object", "null" ], "description": "PHP limits written as php_admin_value; null takes the value of php.ini.", "properties": { "memory_limit": { "type": [ "string", "null" ], "description": "A size such as `256M`, or `-1` for no limit.", "pattern": "^(-1|\\d{1,6}[KMG]?)$", "maxLength": 16 }, "upload_max_filesize": { "type": [ "string", "null" ], "pattern": "^\\d{1,6}[KMG]?$", "maxLength": 16 }, "post_max_size": { "type": [ "string", "null" ], "description": "At least upload_max_filesize.", "pattern": "^\\d{1,6}[KMG]?$", "maxLength": 16 }, "max_execution_time": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 999999 }, "max_input_vars": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 9999999 } } } }, "required": [ "name", "pm", "max_children", "max_requests" ], "title": "PhpProfileRequest" }, "PhpVersion": { "type": "object", "properties": { "version": { "type": "string", "description": "for example `8.4`" }, "installed": { "type": "boolean" }, "default": { "type": "boolean", "description": "the version of the system `php` binary" }, "used_by": { "type": "array", "description": "web domains that use it, as `user/domain`", "items": { "type": "string" } }, "status": { "type": "string", "description": "`active`, `security` (security fixes only), `eol` (end of life) or `unknown`" }, "released": { "type": [ "string", "null" ], "description": "release date, `YYYY-MM-DD`" }, "active_until": { "type": [ "string", "null" ], "description": "end of active support, `YYYY-MM-DD`" }, "eol": { "type": [ "string", "null" ], "description": "end of life, `YYYY-MM-DD`" }, "installable": { "type": "boolean", "description": "whether the catalog allows new installs (7.4 and later)" }, "available": { "type": "boolean", "description": "whether the PHP repository of the server provides it" }, "extensions": { "type": "integer", "description": "modules enabled for PHP-FPM; 0 when not installed" } }, "required": [ "version", "installed", "default", "used_by" ], "title": "PhpVersion" }, "PlanStep": { "type": "object", "properties": { "label": { "type": "string", "description": "What the step does." }, "command": { "type": "string", "description": "The v-* command of the step." } }, "required": [ "label", "command" ] }, "Plugin": { "type": "object", "properties": { "name": { "type": "string" }, "enabled": { "type": "boolean", "description": "whether the plugin is installed" } }, "required": [ "name", "enabled" ], "title": "Plugin" }, "PluginsSettings": { "type": "object", "description": "The `plugins` tab of the server settings.", "properties": { "app_installer": { "type": "boolean" }, "plugins": { "type": "object", "description": "Whether each plugin is installed; setPlugin installs or removes one.", "properties": { "filemanager": { "type": "boolean" }, "web-terminal": { "type": "boolean" }, "cgroups": { "type": "boolean" }, "quota": { "type": "boolean" }, "firewall": { "type": "boolean" }, "malware-scan": { "type": "boolean" } }, "required": [ "filemanager", "web-terminal", "cgroups", "quota", "firewall", "malware-scan" ] } }, "required": [ "app_installer", "plugins" ] }, "PortEntry": { "type": "object", "title": "PortEntry", "description": "One entry of the port registry: a single port or a free range of a user.", "properties": { "port": { "type": "string", "description": "`30001`, or `30010-30019` for a range." }, "start": { "type": "integer" }, "end": { "type": "integer" }, "size": { "type": "integer", "minimum": 1 }, "proto": { "type": "string", "enum": [ "tcp", "udp" ] }, "owner": { "type": "string", "description": "The account that holds the port." }, "app": { "type": [ "string", "null" ], "description": "`manual`, `node:` or `docker:`; null for a free port or range." }, "assigned": { "type": "boolean" }, "public": { "type": "boolean", "description": "Open to the internet in the registry (closed while the owner is suspended)." }, "public_ok": { "type": "boolean", "description": "Whether the port may be opened to the internet." }, "rule": { "type": [ "string", "null" ], "description": "Id of the port's firewall rule, null without one." }, "comment": { "type": [ "string", "null" ] }, "suspended": { "type": "boolean" }, "listen": { "type": "string", "enum": [ "no", "local", "any" ], "description": "Live state: nothing listens, loopback only, or all addresses." }, "created_at": { "type": [ "string", "null" ] } }, "required": [ "port", "start", "end", "size", "proto", "owner", "app", "assigned", "public", "public_ok", "rule", "comment", "suspended", "listen", "created_at" ] }, "PortFinding": { "type": "object", "title": "PortFinding", "description": "A reconciliation finding of the port registry.", "properties": { "type": { "type": "string", "enum": [ "orphan-socket", "foreign-socket", "exposed-private", "missing-rule", "stale-rule", "unmanaged-rule", "orphan-file", "over-limit", "orphan-web" ] }, "title": { "type": "string" }, "user": { "type": [ "string", "null" ] }, "port": { "type": [ "string", "null" ] }, "proto": { "type": [ "string", "null" ] }, "rule": { "type": [ "string", "null" ] }, "detail": { "type": "string" } }, "required": [ "type", "title", "user", "port", "proto", "rule", "detail" ] }, "PortListMeta": { "type": "object", "description": "The totals of a user's port pool and the server range; the port list is not paginated (E34 batch 4 §4.5).", "properties": { "user": { "type": "string" }, "owner": { "type": [ "string", "null" ], "description": "The reseller or administrator whose pool gives and takes back ports; null for administrators." }, "limit": { "type": "string", "description": "PORTS of the package (`unlimited` or a number)." }, "allocated": { "type": "integer", "minimum": 0, "description": "Ports in the pool." }, "assigned": { "type": "integer", "minimum": 0, "description": "Ports reserved or held by an app." }, "public": { "type": "integer", "minimum": 0 }, "free": { "type": "integer", "minimum": 0 }, "tree_total": { "type": [ "integer", "null" ], "description": "A reseller: ports of the reseller and its customers." }, "tree_used": { "type": [ "integer", "null" ], "description": "A reseller: ports given to its customers." }, "firewall": { "type": "boolean", "description": "Whether the firewall is on; without it every listening port is reachable." }, "range": { "type": "object", "properties": { "start": { "type": "integer" }, "end": { "type": "integer" } }, "required": [ "start", "end" ] } }, "required": [ "user", "owner", "limit", "allocated", "assigned", "public", "free", "tree_total", "tree_used", "firewall", "range" ] }, "PortRegistry": { "type": "object", "title": "PortRegistry", "description": "The port registry of the server (Admin → Server → Ports).", "properties": { "range": { "type": "object", "properties": { "start": { "type": "integer" }, "end": { "type": "integer" } }, "required": [ "start", "end" ] }, "firewall": { "type": [ "string", "null" ], "description": "FIREWALL_SYSTEM; null when the firewall is off and every listening port is reachable." }, "users": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "string" }, "owner": { "type": [ "string", "null" ] }, "role": { "type": "string" }, "suspended": { "type": "boolean" }, "limit": { "type": "string", "description": "PORTS of the package (`unlimited` or a number)." }, "allocated": { "type": "integer" }, "assigned": { "type": "integer" }, "public": { "type": "integer" }, "free": { "type": "integer" }, "tree_total": { "type": [ "integer", "null" ] }, "tree_used": { "type": [ "integer", "null" ] } }, "required": [ "user", "owner", "role", "suspended", "limit", "allocated", "assigned", "public", "free", "tree_total", "tree_used" ] } }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/PortEntry" } }, "reserved": { "type": "array", "items": { "type": "object", "properties": { "port": { "type": "string" }, "start": { "type": "integer" }, "end": { "type": "integer" }, "kind": { "type": "string", "enum": [ "system", "admin" ], "description": "`system`: a service of the panel (kept); `admin`: reserved by an administrator." }, "comment": { "type": [ "string", "null" ] } }, "required": [ "port", "start", "end", "kind", "comment" ] } }, "sockets": { "type": "array", "description": "Sockets that listen in the server range.", "items": { "type": "object", "properties": { "proto": { "type": "string", "enum": [ "tcp", "udp" ] }, "port": { "type": "integer" }, "scope": { "type": "string", "enum": [ "local", "any" ] }, "uid": { "type": [ "integer", "null" ] }, "account": { "type": [ "string", "null" ] } }, "required": [ "proto", "port", "scope", "uid", "account" ] } }, "findings": { "type": "array", "items": { "$ref": "#/components/schemas/PortFinding" } } }, "required": [ "range", "firewall", "users", "entries", "reserved", "sockets", "findings" ] }, "PutUserSecretValueRequest": { "type": "object", "description": "PUT /users/{user}/secrets/{name}/value: the next version of a secret (E38).", "properties": { "value": { "type": "string", "description": "The new value, 1 byte to 32 KiB; it is never returned.", "maxLength": 32768 }, "restart": { "type": "boolean", "description": "Restart the running apps that reference the secret, so they read the new value. Default false." } }, "required": [ "value" ], "title": "PutUserSecretValueRequest" }, "RegisterPortRequest": { "type": "object", "properties": { "user": { "type": "string", "pattern": "^[[:alnum:]][-.\\w]{0,28}[[:alnum:]]$" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535 }, "proto": { "type": "string", "enum": [ "tcp", "udp" ] } }, "required": [ "user", "port", "proto" ], "title": "RegisterPortRequest" }, "RenameFileRequest": { "type": "object", "description": "Body of `renameFile` (E34 batch 5 spec §4.2).", "properties": { "path": { "type": "string", "description": "Entry relative to the home directory." }, "name": { "type": "string", "description": "New name in the same folder: no slash, not `.` or `..`.", "maxLength": 255 } }, "required": [ "path", "name" ], "title": "RenameFileRequest" }, "ReplacePhpIniRequest": { "type": "object", "description": "PUT /system/php/versions/{php}/ini/{sapi} (E41 §6, §9): the whole file.", "properties": { "content": { "type": [ "string", "null" ], "description": "The new php.ini, at most 1 MiB.", "maxLength": 1048576 } }, "required": [ "content" ], "title": "ReplacePhpIniRequest" }, "RequestMailLetsEncryptRequest": { "type": "object", "description": "POST /users/{user}/mail-domains/{domain}/letsencrypt.", "properties": { "key_algorithm": { "type": "string", "enum": [ "ecdsa-256", "ecdsa-384", "rsa" ], "examples": [ "ecdsa-256" ] } }, "title": "RequestMailLetsEncryptRequest" }, "RequestMeta": { "type": "object", "description": "The requests of the journal that share the id and that the key may see (E43 B4); the latest is returned.", "properties": { "duplicates": { "type": "integer", "minimum": 1, "description": "How many requests carry the id: 1 unless a client reused it." } }, "required": [ "duplicates" ] }, "RequestPortsRequest": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 1, "maximum": 1000 }, "reason": { "type": [ "string", "null" ], "maxLength": 200 } }, "required": [ "count" ], "title": "RequestPortsRequest" }, "ReservePortRequest": { "type": "object", "properties": { "port": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 65535 }, "proto": { "type": "string", "enum": [ "tcp", "udp" ] }, "comment": { "type": [ "string", "null" ], "pattern": "^[[:alnum:]][[:alnum:] ._-]{0,64}[[:alnum:]]$" } }, "required": [ "proto" ], "title": "ReservePortRequest" }, "RestartServerRequest": { "type": "object", "description": "POST /system/restart (E34 batch 6 spec D61): the host name of the server\nconfirms the restart. The controller compares it with the server's own.", "properties": { "confirm_hostname": { "type": "string", "description": "The host name of the server, as `meta.hostname` of listServices names it.", "maxLength": 255 } }, "required": [ "confirm_hostname" ], "title": "RestartServerRequest" }, "RestoreBackupRequest": { "type": "object", "description": "POST /users/{user}/backups/{backup}/restore.", "properties": { "web": { "type": "array", "items": { "type": "string", "pattern": "^[^,\\s'\"]+$", "maxLength": 255 } }, "dns": { "type": "array", "items": { "type": "string", "pattern": "^[^,\\s'\"]+$", "maxLength": 255 } }, "mail": { "type": "array", "items": { "type": "string", "pattern": "^[^,\\s'\"]+$", "maxLength": 255 } }, "db": { "type": "array", "items": { "type": "string", "pattern": "^[^,\\s'\"]+$", "maxLength": 255 } }, "udir": { "type": "array", "items": { "type": "string", "pattern": "^[^,\\s'\"]+$", "maxLength": 255 } }, "cron": { "type": "boolean" } }, "title": "RestoreBackupRequest" }, "RestoreSnapshotRequest": { "type": "object", "description": "POST /users/{user}/snapshots/{snapshot}/restore.", "properties": { "type": { "type": "string", "enum": [ "web", "dns", "mail", "db", "cron" ] }, "object": { "type": [ "string", "null" ], "pattern": "^[^,\\s'\"]+$", "maxLength": 255 }, "path": { "type": "string", "maxLength": 4096 } }, "title": "RestoreSnapshotRequest" }, "RollbackUserSecretRequest": { "type": "object", "description": "POST /users/{user}/secrets/{name}/rollback: copy a kept version into a new one (E38).", "properties": { "version": { "type": "integer", "description": "A kept version (see `versions` of getSecret).", "minimum": 1, "maximum": 999999999 }, "restart": { "type": "boolean", "description": "Restart the running apps that reference the secret. Default false." } }, "required": [ "version" ], "title": "RollbackUserSecretRequest" }, "RunUpdatesRequest": { "type": "object", "description": "POST /system/updates (E34 batch 6 spec §5.4).", "properties": { "package": { "type": [ "string", "null" ], "description": "The package to update; every package when left out.", "enum": [ "arcpanel", "arcpanel-nginx", "arcpanel-php", null ] } }, "title": "RunUpdatesRequest" }, "SaveFileRequest": { "type": "object", "description": "Body of `saveFile` (E34 batch 5 spec §4.2). `content` may span lines; a\nNUL byte is refused, because binary content is out of scope (§8).", "properties": { "path": { "type": "string", "description": "File relative to the home directory." }, "content": { "type": [ "string", "null" ], "description": "The new text, at most 2 MiB as UTF-8 (`413` above). Line endings are written as sent." }, "hash": { "type": [ "string", "null" ], "description": "`hash` of the version read (readFile), or null to create a new file. A file that changed since answers `409` `E_INUSE`.", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "path", "content", "hash" ], "title": "SaveFileRequest" }, "SearchGroup": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "users", "web_domains", "dns_zones", "dns_records", "mail_domains", "mail_accounts", "databases", "cron_jobs" ] }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/SearchResult" } } }, "required": [ "type", "items" ], "title": "SearchGroup" }, "SearchResult": { "type": "object", "properties": { "name": { "type": "string", "description": "what matched: a domain, `record.domain`, `account@domain`, a database, a cron command or a user name" }, "owner": { "type": "string", "description": "the user that owns the object (the user itself for a user)" }, "parent": { "type": [ "string", "null" ], "description": "the zone of a DNS record, the domain of a mail account" }, "path": { "type": "string", "description": "the object's path under /api/v2" } }, "required": [ "name", "owner", "parent", "path" ], "title": "SearchResult" }, "SecretFlag": { "type": "object", "description": "A secret of the settings: whether one is stored. The value is never returned (D58).", "properties": { "set": { "type": "boolean" } }, "required": [ "set" ] }, "SecuritySettings": { "type": "object", "description": "The `security` tab of the server settings.", "properties": { "API_SYSTEM": { "type": "string", "description": "Read-only through the API (403 on a change)." }, "API": { "type": "string", "description": "Read-only through the API (403 on a change)." }, "API_V1": { "type": "string", "description": "Read-only through the API (403 on a change)." }, "API_ALLOWED_IP": { "type": "string", "description": "Read-only through the API (403 on a change)." }, "LOGIN_STYLE": { "type": "string" }, "INACTIVE_SESSION_TIMEOUT": { "type": "string" }, "POLICY_CSRF_STRICTNESS": { "type": "string" }, "POLICY_SYSTEM_PASSWORD_RESET": { "type": "string" }, "POLICY_SYSTEM_PROTECTED_ADMIN": { "type": "string", "description": "Read-only through the API (403 on a change)." }, "POLICY_SYSTEM_HIDE_ADMIN": { "type": "string", "description": "Read-only through the API (403 on a change)." }, "POLICY_SYSTEM_HIDE_SERVICES": { "type": "string", "description": "Read-only through the API (403 on a change)." }, "POLICY_USER_EDIT_DETAILS": { "type": "string" }, "POLICY_USER_EDIT_WEB_TEMPLATES": { "type": "string" }, "POLICY_USER_EDIT_DNS_TEMPLATES": { "type": "string" }, "POLICY_USER_VIEW_LOGS": { "type": "string" }, "POLICY_USER_DELETE_LOGS": { "type": "string" }, "POLICY_USER_VIEW_SUSPENDED": { "type": "string" }, "POLICY_BACKUP_SUSPENDED_USERS": { "type": "string" }, "POLICY_SYNC_ERROR_DOCUMENTS": { "type": "string" }, "POLICY_SYNC_SKELETON": { "type": "string" }, "ENFORCE_SUBDOMAIN_OWNERSHIP": { "type": "string" }, "POLICY_RESELLER_PACKAGE_SHELLS": { "type": "string" } }, "required": [ "API_SYSTEM", "API", "API_V1", "API_ALLOWED_IP", "LOGIN_STYLE", "INACTIVE_SESSION_TIMEOUT", "POLICY_CSRF_STRICTNESS", "POLICY_SYSTEM_PASSWORD_RESET", "POLICY_SYSTEM_PROTECTED_ADMIN", "POLICY_SYSTEM_HIDE_ADMIN", "POLICY_SYSTEM_HIDE_SERVICES", "POLICY_USER_EDIT_DETAILS", "POLICY_USER_EDIT_WEB_TEMPLATES", "POLICY_USER_EDIT_DNS_TEMPLATES", "POLICY_USER_VIEW_LOGS", "POLICY_USER_DELETE_LOGS", "POLICY_USER_VIEW_SUSPENDED", "POLICY_BACKUP_SUSPENDED_USERS", "POLICY_SYNC_ERROR_DOCUMENTS", "POLICY_SYNC_SKELETON", "ENFORCE_SUBDOMAIN_OWNERSHIP", "POLICY_RESELLER_PACKAGE_SHELLS" ] }, "ServerSettings": { "type": "object", "description": "The server settings by tab (E34 batch 6 D58); `dns`, `mail` and `databases` are left out when the server does not run that system.", "properties": { "general": { "$ref": "#/components/schemas/GeneralSettings" }, "web": { "$ref": "#/components/schemas/WebSettings" }, "dns": { "$ref": "#/components/schemas/DnsSettings" }, "mail": { "$ref": "#/components/schemas/MailSettings" }, "databases": { "$ref": "#/components/schemas/DatabasesSettings" }, "backups": { "$ref": "#/components/schemas/BackupsSettings" }, "ssl": { "$ref": "#/components/schemas/SslSettings" }, "security": { "$ref": "#/components/schemas/SecuritySettings" }, "plugins": { "$ref": "#/components/schemas/PluginsSettings" }, "white-label": { "$ref": "#/components/schemas/WhiteLabelSettings" } }, "required": [ "general", "web", "backups", "ssl", "security", "plugins", "white-label" ] }, "Service": { "type": "object", "properties": { "name": { "type": "string", "description": "the name the start, stop and restart paths take" }, "system": { "type": "string", "description": "what the service is, for example `web server`" }, "running": { "type": "boolean" }, "cpu": { "type": "number", "description": "CPU usage in percent" }, "memory_mb": { "type": "integer", "description": "memory in MB" }, "uptime_minutes": { "type": "integer", "description": "minutes since the service started" } }, "required": [ "name", "system", "running", "cpu", "memory_mb", "uptime_minutes" ], "title": "Service" }, "ServiceListMeta": { "type": "object", "description": "The server the services run on; the service list is not paginated (E34 batch 6 §5.1).", "properties": { "hostname": { "type": "string", "description": "The host name; restartServer takes it as `confirm_hostname`." }, "os": { "type": "string", "description": "The distribution, for example `Ubuntu`." }, "os_version": { "type": "string", "description": "For example `24.04`." }, "arch": { "type": "string", "description": "For example `x86_64`." }, "arcpanel_version": { "type": "string" }, "release": { "type": "string", "description": "The release channel of the panel." }, "uptime_minutes": { "type": "integer", "minimum": 0 }, "load": { "type": "array", "items": { "type": "number" }, "description": "The load averages of 1, 5 and 15 minutes." } }, "required": [ "hostname", "os", "os_version", "arch", "arcpanel_version", "release", "uptime_minutes", "load" ] }, "ServiceLog": { "type": "object", "properties": { "service": { "type": "string", "description": "the service, as listServices names it" }, "lines": { "type": "array", "description": "journal lines in `short-iso` form, the newest last", "items": { "type": "string" } } }, "required": [ "service", "lines" ], "title": "ServiceLog" }, "ServiceStatus": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "cpu", "mem", "disk", "net", "web", "dns", "mail", "db" ] }, "text": { "type": "string", "description": "the report as the command prints it" } }, "required": [ "kind", "text" ], "title": "ServiceStatus" }, "SetAppProcessEnvRequest": { "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$", "maxLength": 128 }, "value": { "type": [ "string", "null" ], "maxLength": 4096 } }, "required": [ "name" ] }, "maxItems": 200, "uniqueItems": true } }, "required": [ "entries" ], "title": "SetAppProcessEnvRequest" }, "SetBackupExclusionsRequest": { "type": "object", "description": "PUT /users/{user}/backup-exclusions.", "properties": { "web": { "type": "array", "items": { "type": "string", "pattern": "^[^,\\s'\"]+", "maxLength": 4096 } }, "dns": { "type": "array", "items": { "type": "string", "pattern": "^[^,\\s'\"]+", "maxLength": 4096 } }, "mail": { "type": "array", "items": { "type": "string", "pattern": "^[^,\\s'\"]+", "maxLength": 4096 } }, "db": { "type": "array", "items": { "type": "string", "pattern": "^[^,\\s'\"]+", "maxLength": 4096 } }, "cron": { "type": "array", "items": { "type": "string", "pattern": "^[^,\\s'\"]+", "maxLength": 4096 } }, "user": { "type": "array", "items": { "type": "string", "pattern": "^[^,\\s'\"]+", "maxLength": 4096 } } }, "title": "SetBackupExclusionsRequest" }, "SetCronReportsRequest": { "type": "object", "description": "PUT /users/{user}/cron-reports.", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ], "title": "SetCronReportsRequest" }, "SetDatabaseHostPasswordRequest": { "type": "object", "description": "PUT /system/settings/databases/hosts/{type}/{host}/password (E34 batch 6\nspec §5.7): the password of a database user on a MySQL host, as on the\npage. The password reaches the command in a file and is never answered.", "properties": { "user": { "type": "string", "description": "The database user, for example `root`.", "pattern": "^[A-Za-z0-9_.-]+$", "maxLength": 64 }, "password": { "type": "string", "description": "The new password: 8 to 256 characters, no quotes and no backslash.", "minLength": 8, "maxLength": 256 } }, "required": [ "user", "password" ], "title": "SetDatabaseHostPasswordRequest" }, "SetDockerAppDomainRequest": { "type": "object", "properties": { "domain": { "type": "string", "pattern": "^[^\\s\\/]+$", "maxLength": 253 } }, "required": [ "domain" ], "title": "SetDockerAppDomainRequest" }, "SetDockerAppEnvRequest": { "type": "object", "properties": { "vars": { "type": "array", "items": { "type": "string" }, "maxItems": 100 } }, "required": [ "vars" ], "title": "SetDockerAppEnvRequest" }, "SetDockerAppLimitsRequest": { "type": "object", "properties": { "cpus": { "type": "string", "pattern": "^\\d{1,3}(\\.\\d{1,2})?$" }, "memory_mb": { "type": "integer", "minimum": 32, "maximum": 9999999 } }, "required": [ "cpus", "memory_mb" ], "title": "SetDockerAppLimitsRequest" }, "SetMailDomainRelayRequest": { "type": "object", "description": "PUT /users/{user}/mail-domains/{domain}/smtp-relay.", "properties": { "host": { "type": "string", "description": "The relay host.", "pattern": "^[\\w.-]+$", "maxLength": 253 }, "port": { "type": "integer", "description": "Defaults to 587.", "minimum": 1, "maximum": 65535 }, "username": { "type": [ "string", "null" ], "examples": [ "relay-user" ], "maxLength": 255 }, "password": { "type": [ "string", "null" ], "description": "Sent to the command and never returned.", "maxLength": 255 } }, "required": [ "host" ], "title": "SetMailDomainRelayRequest" }, "SetMailDomainSslRequest": { "type": "object", "description": "PUT /users/{user}/mail-domains/{domain}/ssl. The certificate is required.", "properties": { "certificate": { "type": "string", "description": "PEM of the certificate.", "maxLength": 65535 }, "key": { "type": [ "string", "null" ], "description": "PEM of the private key. Required when this is the domain's first uploaded certificate.", "maxLength": 65535 }, "ca": { "type": [ "string", "null" ], "description": "PEM of the certificate chain.", "maxLength": 65535 } }, "required": [ "certificate" ], "title": "SetMailDomainSslRequest" }, "SetNodeAppEnvRequest": { "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$", "maxLength": 128 }, "value": { "type": [ "string", "null" ], "maxLength": 4096 } }, "required": [ "name" ] }, "maxItems": 200, "uniqueItems": true } }, "required": [ "entries" ], "title": "SetNodeAppEnvRequest" }, "SetNodeEnabledRequest": { "type": "object", "description": "PUT /users/{user}/node", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ], "title": "SetNodeEnabledRequest" }, "SetPhpExtensionRequest": { "type": "object", "description": "PUT /system/php/versions/{php}/extensions/{name} (E41 §9).", "properties": { "installed": { "description": "`true` installs the extension as the system task (`202`); an installed one stays. Removing is `DELETE`.", "enum": [ "yes", "on", "1", 1, "true", true ] }, "fpm": { "type": "boolean", "description": "Turn the module on or off for PHP-FPM." }, "cli": { "type": "boolean", "description": "Turn the module on or off for the command line." } }, "title": "SetPhpExtensionRequest" }, "SetPhpVersionsRequest": { "type": "object", "description": "PUT /system/settings/web/php (E34 batch 6 spec §5.7): the full list of\nPHP versions the server should have.", "properties": { "versions": { "type": "array", "description": "Every PHP version to keep or install; an installed version left out is removed.", "items": { "type": "string", "pattern": "^\\d\\.\\d$" }, "maxItems": 20, "uniqueItems": true } }, "required": [ "versions" ], "title": "SetPhpVersionsRequest" }, "SetPluginRequest": { "type": "object", "description": "PUT /system/settings/plugins/{plugin} (E34 batch 6 spec §5.7).", "properties": { "enabled": { "type": "boolean", "description": "true installs the plugin, false removes it." } }, "required": [ "enabled" ], "title": "SetPluginRequest" }, "SetPortPublicOkRequest": { "type": "object", "properties": { "public_ok": { "type": "boolean" } }, "required": [ "public_ok" ], "title": "SetPortPublicOkRequest" }, "SetPortPublicRequest": { "type": "object", "properties": { "public": { "type": "boolean" }, "rule": { "type": "integer", "description": "Administrators only: link this existing firewall rule on the port instead of adding one (403 for anyone else).", "minimum": 1 } }, "required": [ "public" ], "title": "SetPortPublicRequest" }, "SetPortRangeRequest": { "type": "object", "properties": { "start": { "type": "integer", "minimum": 1024, "maximum": 65534 }, "end": { "type": "integer", "maximum": 65535 } }, "required": [ "start", "end" ], "title": "SetPortRangeRequest" }, "SetUpdateSettingsRequest": { "type": "object", "description": "PUT /system/updates/settings (E34 batch 6 spec §5.4): fields left out keep\ntheir value.", "properties": { "auto_update": { "type": "boolean", "description": "Update the panel packages every day (a cron job of the administrator)." }, "send_email": { "type": "boolean", "description": "Send an e-mail to the administrator after an update." }, "send_log": { "type": "boolean", "description": "Attach the log of the update to that e-mail." } }, "title": "SetUpdateSettingsRequest" }, "SetWebDomainPhpRequest": { "type": "object", "description": "PUT /users/{user}/web-domains/{domain}/php (E41 §7.2, §9).", "properties": { "version": { "type": "string", "description": "An installed version the package allows, for example `8.4`; the current one when left out.", "pattern": "^\\d{1,2}\\.\\d{1,2}$" }, "profile": { "type": "string", "description": "A PHP-FPM profile the package allows; the current one when left out.", "pattern": "^[a-z0-9][a-z0-9-]{0,31}$" } }, "title": "SetWebDomainPhpRequest" }, "Snapshot": { "type": "object", "properties": { "id": { "type": "string", "description": "full restic snapshot id" }, "short_id": { "type": "string", "description": "short restic snapshot id" }, "created_at": { "type": [ "string", "null" ], "description": "creation time in the server's time zone, YYYY-MM-DDTHH:MM:SS" }, "hostname": { "type": "string", "description": "hostname recorded in the snapshot" }, "paths": { "type": "array", "description": "backed-up paths", "items": { "type": "string" } }, "content": { "type": "object", "properties": { "web": { "type": "array", "items": { "type": "string" } }, "dns": { "type": "array", "items": { "type": "string" } }, "mail": { "type": "array", "items": { "type": "string" } }, "db": { "type": "array", "items": { "type": "string" } }, "udir": { "type": "array", "items": { "type": "string" } }, "cron": { "type": "boolean" } }, "required": [ "web", "dns", "mail", "db", "udir", "cron" ] } }, "required": [ "id", "short_id", "created_at", "hostname", "paths", "content" ], "title": "Snapshot" }, "SnapshotFileEntry": { "type": "object", "properties": { "name": { "type": "string" }, "path": { "type": "string", "description": "path relative to the home directory" }, "type": { "type": "string", "enum": [ "file", "directory", "link", "other" ] }, "size": { "type": "integer" }, "mode": { "type": "string", "description": "octal mode" }, "owner": { "type": "string" }, "group": { "type": "string" }, "modified_at": { "type": [ "string", "null" ], "description": "creation time in the server's time zone, YYYY-MM-DDTHH:MM:SS" }, "link_target": { "type": [ "string", "null" ] }, "link_type": { "type": [ "string", "null" ], "enum": [ "d", "f", "missing", "o", null ] }, "link_inside": { "type": "boolean" }, "mime": { "type": [ "string", "null" ] }, "writable": { "type": "boolean" }, "valid_name": { "type": "boolean" } }, "required": [ "name", "path", "type", "size", "mode", "owner", "group", "modified_at", "link_target", "link_type", "link_inside", "mime", "writable", "valid_name" ], "title": "SnapshotFileEntry" }, "SshKey": { "type": "object", "properties": { "id": { "type": "string", "description": "the key's comment; URL-encode it in paths" }, "fingerprint": { "type": "string", "description": "as `ssh-keygen -l` prints it, for example `SHA256:…`" } }, "required": [ "id", "fingerprint" ], "title": "SshKey" }, "SslSettings": { "type": "object", "description": "The `ssl` tab of the server settings.", "properties": { "certificate": { "type": "string" }, "key": { "$ref": "#/components/schemas/SecretFlag" }, "subject": { "type": "string", "description": "Read-only." }, "aliases": { "type": "string", "description": "Read-only." }, "issuer": { "type": "string", "description": "Read-only." }, "not_before": { "type": "string", "description": "Read-only." }, "not_after": { "type": "string", "description": "Read-only." }, "signature": { "type": "string", "description": "Read-only." }, "public_key": { "type": "string", "description": "Read-only." } }, "required": [ "certificate", "key", "subject", "aliases", "issuer", "not_before", "not_after", "signature", "public_key" ] }, "StartAppProcessTaskRequest": { "type": "object", "properties": { "task": { "type": "string", "enum": [ "composer-install", "migrate", "pip-install", "bundle-install", "custom" ] }, "command": { "type": [ "string", "null" ], "pattern": "^[^\\x00-\\x1f\\x7f]{1,2048}$", "maxLength": 2048 } }, "required": [ "task" ], "title": "StartAppProcessTaskRequest" }, "StartDockerAppTaskRequest": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "install", "update", "rollback", "snapshot" ] }, "version": { "type": [ "string", "null" ], "pattern": "^[0-9A-Za-z][0-9A-Za-z._+-]{0,39}$" } }, "required": [ "action" ], "title": "StartDockerAppTaskRequest" }, "StartMalwareScanRequest": { "type": "object", "description": "POST /users/{user}/malware/scans (E25 batch 1 spec §9).", "properties": { "domain": { "type": [ "string", "null" ], "description": "A web domain of the user; every web domain when left out.", "maxLength": 253 } }, "title": "StartMalwareScanRequest" }, "StartUploadRequest": { "type": "object", "description": "Body of `startUpload` (E34 batch 5 spec §4.3).", "properties": { "path": { "type": [ "string", "null" ], "description": "Folder relative to the home directory; the home directory when left out." }, "name": { "type": "string", "description": "Name of the file: no slash, not `.` or `..`.", "maxLength": 255 }, "size": { "type": "integer", "description": "Bytes of the whole file.", "minimum": 0 }, "relative_path": { "type": [ "string", "null" ], "description": "For a file of a folder upload: its path below `path`, ending in `name`; the missing folders are created when the upload finishes.", "maxLength": 4096 }, "modified_at": { "type": [ "integer", "null" ], "description": "The file's modification time as the client knows it (for example Unix milliseconds). With the folder, the name and the size it finds the session to resume.", "minimum": 0 } }, "required": [ "name", "size" ], "title": "StartUploadRequest" }, "StatsMonth": { "type": "object", "properties": { "month": { "type": "string", "description": "YYYY-MM" }, "package": { "type": "string", "description": "the package of the account at the time; empty in totals" }, "disk_mb": { "type": "object", "description": "Usage and quota in MB; the limit is null when unlimited.", "properties": { "used": { "type": "integer" }, "limit": { "type": [ "integer", "null" ] }, "web": { "type": "integer" }, "mail": { "type": "integer" }, "databases": { "type": "integer" }, "directories": { "type": "integer", "description": "the user's directories outside web, mail and databases" } }, "required": [ "used", "limit", "web", "mail", "databases", "directories" ] }, "bandwidth_mb": { "type": "object", "description": "Traffic and its limit in MB; the limit is null when unlimited.", "properties": { "used": { "type": "integer" }, "limit": { "type": [ "integer", "null" ] } }, "required": [ "used", "limit" ] }, "ip_addresses": { "type": "integer" }, "users": { "type": [ "integer", "null" ], "description": "accounts counted in server or tree totals; null for one account" }, "web_domains": { "type": "integer" }, "web_ssl": { "type": "integer" }, "web_aliases": { "type": "integer" }, "dns_domains": { "type": "integer" }, "dns_records": { "type": "integer" }, "mail_domains": { "type": "integer" }, "mail_accounts": { "type": "integer" }, "databases": { "type": "integer" }, "cron_jobs": { "type": "integer" }, "backups": { "type": "integer" } }, "required": [ "month", "package", "disk_mb", "bandwidth_mb", "ip_addresses", "users", "web_domains", "web_ssl", "web_aliases", "dns_domains", "dns_records", "mail_domains", "mail_accounts", "databases", "cron_jobs", "backups" ], "title": "StatsMonth" }, "StoreAppProcessRequest": { "type": "object", "properties": { "domain": { "type": "string", "pattern": "^[^\\s\\/]+$", "maxLength": 253 }, "name": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,31}$" }, "preset": { "type": "string", "pattern": "^[a-z0-9-]{1,40}$" }, "start": { "type": [ "string", "null" ], "pattern": "^[^\\x00-\\x1f\\x7f]{1,2048}$", "maxLength": 2048 }, "cwd": { "type": [ "string", "null" ], "pattern": "^(\\.|[A-Za-z0-9_][A-Za-z0-9._\\/@+-]{0,199})$" }, "memory_mb": { "type": [ "integer", "null" ], "minimum": 32, "maximum": 999999 }, "cpus": { "type": [ "string", "null" ], "pattern": "^\\d{1,2}(\\.\\d{1,2})?$" }, "kind": { "type": [ "string", "null" ], "enum": [ "web", "worker", null ] }, "template": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9_.-]{1,64}$" } }, "required": [ "domain", "name", "preset" ], "title": "StoreAppProcessRequest" }, "StoreCronJobRequest": { "type": "object", "description": "POST /users/{user}/cron-jobs.", "properties": { "schedule": { "type": "string", "description": "Five crontab fields, for example `*\\/5 * * * *`.", "maxLength": 640 }, "command": { "type": "string", "maxLength": 4096 } }, "required": [ "schedule", "command" ], "title": "StoreCronJobRequest" }, "StoreDatabaseRequest": { "type": "object", "description": "POST /users/{user}/databases. Names are the short names, without the owner prefix.", "properties": { "name": { "type": "string", "description": "The database name without the owner prefix.", "pattern": "^[A-Za-z0-9_]+$", "maxLength": 64 }, "db_user": { "type": "string", "description": "The database user without the owner prefix.", "pattern": "^[A-Za-z0-9_]+$", "maxLength": 32 }, "password": { "type": "string", "pattern": "^(?=.*[a-z])(?=.*[A-Z])(?=.*\\d)(.){8,}$", "maxLength": 256 }, "type": { "type": "string", "description": "mysql or pgsql. The first type of the server when left out.", "pattern": "^[a-z]+$", "maxLength": 16 }, "host": { "type": "string", "description": "A database host. The first one when left out.", "pattern": "^[\\w.:-]+$", "maxLength": 253 }, "charset": { "type": "string", "enum": [ "big5", "dec8", "cp850", "hp8", "koi8r", "latin1", "latin2", "swe7", "ascii", "ujis", "sjis", "hebrew", "tis620", "euckr", "koi8u", "gb2312", "greek", "cp1250", "gbk", "latin5", "armscii8", "utf8", "utf8mb4", "ucs2", "cp866", "keybcs2", "macce", "macroman", "cp852", "latin7", "cp1251", "cp1256", "cp1257", "binary", "geostd8", "cp932", "eucjpms" ] }, "send_credentials_to": { "type": [ "string", "null" ], "format": "email", "description": "An address that receives the database settings.", "maxLength": 255 } }, "required": [ "name", "db_user", "password" ], "title": "StoreDatabaseRequest" }, "StoreDnsRecordRequest": { "type": "object", "description": "POST /users/{user}/dns-zones/{domain}/records. The name is lowercased\nand the type uppercased, as the command stores them.", "properties": { "name": { "type": "string", "description": "The record name, `@` for the zone itself.", "maxLength": 253 }, "type": { "type": "string", "description": "One of the DNS record types.", "enum": [ "A", "AAAA", "CAA", "CNAME", "DNSKEY", "DS", "IPSECKEY", "KEY", "MX", "NS", "PTR", "SPF", "SRV", "TLSA", "TXT" ] }, "value": { "type": "string", "description": "The record value.", "maxLength": 4096 }, "priority": { "type": [ "integer", "null" ], "description": "MX and SRV only.", "minimum": 0, "maximum": 65535 }, "ttl": { "type": [ "integer", "null" ], "description": "Seconds. Null or left out keeps the zone's TTL.", "minimum": 1, "maximum": 2147483647 } }, "required": [ "name", "type", "value" ], "title": "StoreDnsRecordRequest" }, "StoreDnsZoneRequest": { "type": "object", "description": "POST /users/{user}/dns-zones. The domain is lowercased and loses a leading \"www.\".", "properties": { "domain": { "type": "string", "description": "The zone name.", "pattern": "^[\\pL\\pN]([\\pL\\pN-]*[\\pL\\pN])?(\\.[\\pL\\pN]([\\pL\\pN-]*[\\pL\\pN])?)+$", "maxLength": 253 }, "ip": { "type": "string", "description": "One of the user's addresses; the first one when left out." }, "template": { "type": [ "string", "null" ], "description": "A DNS template. Needs the right to change templates.", "pattern": "^[\\w.-]*$", "maxLength": 100 }, "nameservers": { "type": "array", "description": "Name servers, one to eight. The user's own when left out.", "items": { "type": "string", "pattern": "^[\\pL\\pN._-]+$", "maxLength": 253 }, "minItems": 1, "maxItems": 8 }, "dnssec": { "type": "boolean", "description": "Sign the zone. Refused when the server has no DNSSEC." }, "ttl": { "type": "integer", "description": "Seconds. 14400 when left out.", "minimum": 1, "maximum": 2147483647 }, "expiry": { "type": "string", "format": "date", "description": "YYYY-MM-DD. One year from today when left out." } }, "required": [ "domain" ], "title": "StoreDnsZoneRequest" }, "StoreDockerAppRequest": { "type": "object", "properties": { "slug": { "type": "string", "pattern": "^[a-z][a-z0-9-]{1,31}$" }, "name": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,30}[a-z0-9]$" }, "domain": { "type": [ "string", "null" ], "pattern": "^[^\\s\\/]+$", "maxLength": 253 }, "version": { "type": [ "string", "null" ], "pattern": "^[0-9A-Za-z][0-9A-Za-z._+-]{0,39}$" }, "vars": { "type": [ "array", "null" ], "items": { "type": "string" }, "maxItems": 100 } }, "required": [ "slug", "name" ], "title": "StoreDockerAppRequest" }, "StoreFirewallBanRequest": { "type": "object", "description": "POST /system/firewall/bans (E34 batch 6 spec §5.3): the fields of the Ban\nIP address page.", "properties": { "ip": { "type": "string", "description": "An IPv4 or IPv6 address, or a network in CIDR format.", "pattern": "^[0-9A-Fa-f:.\\/]{2,64}$" }, "chain": { "type": "string", "enum": [ "SSH", "WEB", "FTP", "DNS", "MAIL", "DB", "ARCPANEL" ] } }, "required": [ "ip", "chain" ], "title": "StoreFirewallBanRequest" }, "StoreFirewallIpsetRequest": { "type": "object", "description": "POST /system/firewall/ipsets (E34 batch 6 spec §5.3): the fields of the\nAdd IP list page.", "properties": { "name": { "type": "string", "pattern": "^[\\w.-]{1,255}$" }, "source": { "type": "string", "description": "A URL, `script:PATH` or a file on the server with one address or network per line.", "maxLength": 255 }, "ip_version": { "type": "string", "enum": [ "v4", "v6" ] }, "auto_update": { "type": "boolean", "description": "Whether the list is read again every day; off by default." } }, "required": [ "name", "source", "ip_version" ], "title": "StoreFirewallIpsetRequest" }, "StoreFirewallRuleRequest": { "type": "object", "description": "POST /system/firewall/rules (E34 batch 6 spec §5.3): the fields of the Add\nrule page. `action` and `protocol` are uppercased and a numeric `port`\nbecomes text, as the commands take them; the commands check the formats\nof the port and the address.", "properties": { "action": { "type": "string", "enum": [ "DROP", "ACCEPT" ] }, "protocol": { "type": "string", "enum": [ "TCP", "UDP", "ICMP" ] }, "port": { "type": "string", "description": "A port, a range (`80-82`) or a list (`80,443`); `0` (the default) is every port.", "maxLength": 255 }, "source": { "type": "string", "description": "An address, a network in CIDR format, or `ipset:NAME` for an IPv4 IPset list.", "maxLength": 255 }, "comment": { "type": [ "string", "null" ], "maxLength": 255 } }, "required": [ "action", "protocol", "source" ], "title": "StoreFirewallRuleRequest" }, "StoreIpRequest": { "type": "object", "description": "POST /system/ips (E34 batch 6 spec §5.2), the fields of the Add IP\naddress page. The controller checks that `interface` is one of the\nserver's and `owner` an account, after the role check.", "properties": { "ip": { "type": "string" }, "netmask": { "type": "string", "description": "A netmask (`255.255.255.0`) or a prefix length.", "pattern": "^[0-9A-Fa-f:.\\/]{1,45}$", "maxLength": 45 }, "interface": { "type": "string", "description": "One of listInterfaces.", "maxLength": 64 }, "owner": { "type": "string", "description": "The account the address belongs to; the root administrator when left out.", "maxLength": 64 }, "shared": { "type": "boolean", "description": "Shared by every account (the default), or dedicated to `owner`." }, "name": { "type": [ "string", "null" ], "description": "The domain assigned to the address.", "pattern": "^[A-Za-z0-9.-]*$", "maxLength": 255 }, "nat": { "type": [ "string", "null" ], "description": "The public address in front of this one (NAT)." } }, "required": [ "ip", "netmask", "interface" ], "title": "StoreIpRequest" }, "StoreMailAccountRequest": { "type": "object", "description": "POST /users/{user}/mail-domains/{domain}/accounts.", "properties": { "account": { "type": "string", "description": "The local part.", "pattern": "^[\\w.-]+$", "maxLength": 64 }, "password": { "type": "string", "pattern": "^(?=.*[a-z])(?=.*[A-Z])(?=.*\\d)(.){8,}$" }, "quota_mb": { "type": [ "integer", "null" ], "description": "Megabytes, or null for unlimited.", "minimum": 1, "maximum": 999999 }, "aliases": { "type": "array", "items": { "type": "string", "pattern": "^[\\w.-]+$", "maxLength": 64 } }, "forwards": { "type": "array", "items": { "type": "string", "pattern": "^[\\w.+-]+@[\\w.-]+$", "maxLength": 255 } }, "forward_only": { "type": "boolean" }, "rate_limit": { "type": [ "integer", "null" ], "description": "Messages per hour. Administrators only.", "minimum": 1, "maximum": 999999 }, "send_credentials_to": { "type": [ "string", "null" ], "format": "email", "description": "An address that receives the account's settings.", "maxLength": 255 } }, "required": [ "account", "password" ], "title": "StoreMailAccountRequest" }, "StoreMailDomainRequest": { "type": "object", "description": "POST /users/{user}/mail-domains. The domain is lowercased and loses a leading \"www.\".", "properties": { "domain": { "type": "string", "description": "The mail domain.", "pattern": "^[\\pL\\pN]([\\pL\\pN-]*[\\pL\\pN])?(\\.[\\pL\\pN]([\\pL\\pN-]*[\\pL\\pN])?)+$", "maxLength": 253 }, "antispam": { "type": "boolean", "description": "Mark incoming spam. On when left out and the server has a spam filter." }, "antivirus": { "type": "boolean", "description": "Scan incoming mail. On when left out and the server has an anti-virus." }, "dkim": { "type": "boolean", "description": "Sign outgoing mail. On when left out." } }, "required": [ "domain" ], "title": "StoreMailDomainRequest" }, "StoreNodeAppRequest": { "type": "object", "properties": { "domain": { "type": "string", "pattern": "^[^\\s\\/]+$", "maxLength": 253 }, "start": { "type": [ "string", "null" ], "pattern": "^(npm:[A-Za-z0-9][A-Za-z0-9:._-]{0,63}|[A-Za-z0-9_][A-Za-z0-9._\\/@+-]{0,199})$", "maxLength": 200 }, "version": { "type": [ "string", "null" ], "pattern": "^(default|\\d{1,3}\\.\\d{1,3}\\.\\d{1,3})$" }, "port": { "type": [ "string", "null" ], "pattern": "^(auto|\\d{4,5})$" }, "cwd": { "type": [ "string", "null" ], "pattern": "^(\\.|[A-Za-z0-9_][A-Za-z0-9._\\/@+-]{0,199})$" }, "instances": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 999 }, "template": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9_.-]{1,64}$" }, "name": { "type": [ "string", "null" ], "pattern": "^[a-z0-9][a-z0-9._-]{0,39}$" } }, "required": [ "domain" ], "title": "StoreNodeAppRequest" }, "StorePackageRequest": { "type": "object", "description": "POST /packages: the name is required, every other field takes the value of the add form.", "properties": { "name": { "type": "string", "pattern": "^[[:alnum:]][-.\\w]*$", "maxLength": 60 }, "templates": { "type": "object", "properties": { "web": { "type": "string", "pattern": "^[[:alnum:]][-.\\w]*$", "maxLength": 100 }, "backend": { "type": "string", "pattern": "^[[:alnum:]][-.\\w]*$", "maxLength": 100 }, "proxy": { "type": "string", "pattern": "^[[:alnum:]][-.\\w]*$", "maxLength": 100 }, "dns": { "type": "string", "pattern": "^[[:alnum:]][-.\\w]*$", "maxLength": 100 } } }, "limits": { "type": "object", "properties": { "rate_limit": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "backups": { "type": "integer", "minimum": 0, "maximum": 1000 }, "web_domains": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100000000 }, "web_aliases": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100000000 }, "dns_domains": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100000000 }, "dns_records": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100000000 }, "mail_domains": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100000000 }, "mail_accounts": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100000000 }, "databases": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100000000 }, "cron_jobs": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100000000 }, "disk_mb": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100000000 }, "bandwidth_mb": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100000000 } } }, "resources": { "type": "object", "properties": { "cpu_quota": { "type": [ "string", "null" ], "pattern": "^\\d+(%|ms|s|[KMGT])?$", "maxLength": 20 }, "cpu_quota_period": { "type": [ "string", "null" ], "pattern": "^\\d+(%|ms|s|[KMGT])?$", "maxLength": 20 }, "memory_limit": { "type": [ "string", "null" ], "pattern": "^\\d+(%|ms|s|[KMGT])?$", "maxLength": 20 }, "swap_limit": { "type": [ "string", "null" ], "pattern": "^\\d+(%|ms|s|[KMGT])?$", "maxLength": 20 } } }, "shell": { "type": "string", "pattern": "^[[:alnum:]][-.\\w]*$", "maxLength": 100 }, "nameservers": { "type": "array", "items": { "type": "string", "pattern": "^([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z0-9-]+$", "maxLength": 253 }, "minItems": 2, "maxItems": 10 }, "backups_incremental": { "type": "boolean" }, "reseller": { "type": "object", "properties": { "users": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100000 }, "packages": { "type": "array", "items": { "type": "string", "pattern": "^(\\*|[[:alnum:]][-.\\w]*)$", "maxLength": 100 } }, "visible": { "type": "boolean" } } }, "ports": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 65535 }, "node": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "versions": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 999 }, "allowed": { "type": "string", "pattern": "^(lts|\\*|\\d{1,3}(,\\d{1,3})*)$", "maxLength": 100 }, "apps": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 999 } } }, "docker": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "apps": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 999 }, "cpus": { "type": [ "string", "null" ], "pattern": "^\\d{1,3}(\\.\\d{1,2})?$", "maxLength": 20 }, "memory": { "type": [ "string", "null" ], "pattern": "^\\d{1,7}[MG]?$", "maxLength": 20 } } }, "app_processes": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "max": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 999 }, "memory": { "type": [ "string", "null" ], "pattern": "^\\d{1,7}[MG]?$", "maxLength": 20 }, "cpus": { "type": [ "string", "null" ], "pattern": "^\\d{1,2}(\\.\\d{1,2})?$", "maxLength": 20 } } }, "php": { "type": "object", "properties": { "versions": { "type": "string", "pattern": "^(\\*|\\d{1,2}\\.\\d{1,2}(,\\d{1,2}\\.\\d{1,2})*)$", "maxLength": 200 }, "profiles": { "type": "string", "pattern": "^(\\*|[a-z0-9][a-z0-9-]{0,31}(,[a-z0-9][a-z0-9-]{0,31})*)$", "maxLength": 500 }, "default_profile": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,31}$" } } } }, "required": [ "name" ], "title": "StorePackageRequest" }, "StoreUserRequest": { "type": "object", "description": "POST /users: the account of the create wizard (E11 spec §7.3). Role,\nowner and login_disabled are an administrator's choices; for a reseller\nthe new user is always its own customer.", "properties": { "username": { "type": "string", "description": "The login name: 2 to 30 of a-z, 0-9, dot, dash and underscore.", "pattern": "^[a-z0-9][-.a-z0-9_]*[a-z0-9]$", "minLength": 2, "maxLength": 30 }, "password": { "type": "string", "description": "At least 8 characters with a lower-case and an upper-case letter and a digit.", "pattern": "\\d", "minLength": 8, "maxLength": 256 }, "email": { "type": "string", "format": "email", "maxLength": 254 }, "name": { "type": "string", "description": "The full name.", "maxLength": 100 }, "package": { "type": "string", "description": "A package the caller may assign (see GET /packages).", "pattern": "^[[:alnum:]][-.\\w]*$", "maxLength": 100 }, "language": { "type": [ "string", "null" ], "description": "A language of the server; the server language when left out.", "pattern": "^[a-z]{2,3}(-[a-z]{2})?$", "maxLength": 10 }, "role": { "anyOf": [ { "description": "Administrators only.", "$ref": "#/components/schemas/ApiRole" }, { "type": "null" } ] }, "owner": { "type": [ "string", "null" ], "description": "Administrators only: the administrator or a reseller that owns a new user.", "pattern": "^[[:alnum:]][-.\\w]*$", "maxLength": 32 }, "login_disabled": { "type": [ "boolean", "null" ], "description": "Administrators only." } }, "required": [ "username", "password", "email", "name", "package" ], "title": "StoreUserRequest" }, "StoreWebDomainRequest": { "type": "object", "description": "POST /users/{user}/web-domains: the fields of the add page (web/add/web).\nThe domain is lowercased and loses a leading \"www.\".", "properties": { "domain": { "type": "string", "description": "The domain name; IDNs are accepted as Unicode.", "pattern": "^[\\pL\\pN]([\\pL\\pN-]*[\\pL\\pN])?(\\.[\\pL\\pN]([\\pL\\pN-]*[\\pL\\pN])?)+$", "maxLength": 253 }, "ip": { "type": "string", "description": "One of the user's addresses (v-list-user-ips); the first one when left out." }, "aliases": { "type": "array", "description": "Replace the default alias www.DOMAIN.", "items": { "type": "string", "pattern": "^[\\pL\\pN*_.-]+$", "maxLength": 253 }, "maxItems": 500 }, "dns": { "type": "boolean", "description": "Also add a DNS zone for the domain, with the public address of the IP." }, "mail": { "type": "boolean", "description": "Also add a mail domain." }, "templates": { "type": "object", "properties": { "web": { "type": "string", "description": "A web template of the server (v-list-web-templates).", "pattern": "^[\\w.-]+$", "maxLength": 100 }, "backend": { "type": "string", "description": "A PHP-FPM backend template, on servers with a backend.", "pattern": "^[\\w.-]+$", "maxLength": 100 }, "proxy": { "type": "string", "description": "A proxy template, on servers with a proxy; it also turns the proxy on.", "pattern": "^[\\w.-]+$", "maxLength": 100 } } }, "proxy": { "type": "boolean", "description": "Turns the proxy in front of the web server on or off." }, "proxy_extensions": { "type": "array", "description": "Extensions the proxy serves itself.", "items": { "type": "string", "pattern": "^[\\w.-]+$", "maxLength": 20 }, "maxItems": 200 }, "fastcgi_cache": { "type": "object", "description": "The NGINX FastCGI cache, on servers where NGINX runs PHP-FPM.", "properties": { "enabled": { "type": "boolean" }, "duration": { "type": [ "string", "null" ], "description": "How long a page is kept, such as 2m (the default), 1h or 1d.", "pattern": "^\\d+[smhd]$" } } }, "backend_port": { "type": [ "string", "null" ], "description": "`auto` or a port of the owner's pool, for a template that takes an app port (E6).", "pattern": "^(auto|\\d{1,5})$" } }, "required": [ "domain" ], "title": "StoreWebDomainRequest" }, "SystemPackage": { "type": "object", "properties": { "slug": { "type": "string", "description": "the id the install and remove paths take" }, "name": { "type": "string" }, "summary": { "type": "string" }, "category": { "type": "string", "description": "`runtime`, `media` or `tooling`" }, "provides": { "type": "array", "description": "runtimes the entry provides to the templates, for example `python`", "items": { "type": "string" } }, "packages": { "type": "array", "description": "the distribution packages of the entry", "items": { "type": "string" } }, "available": { "type": "boolean", "description": "whether the distribution release of the server has the packages" }, "status": { "type": "string", "description": "`installed`, `partial` or `missing`" }, "source": { "type": [ "string", "null" ], "description": "`arcpanel` (installed by the panel, which may remove it) or `system`" }, "version": { "type": [ "string", "null" ], "description": "the installed version" }, "upgradable": { "type": "boolean", "description": "whether the archive has a newer version" }, "domains": { "type": "array", "description": "web domains whose template needs the entry, as `user/domain`", "items": { "type": "string" } }, "used_by": { "type": "integer", "description": "the number of those web domains" } }, "required": [ "slug", "name", "summary", "category", "provides", "packages", "available", "status", "source", "version", "upgradable", "domains", "used_by" ], "title": "SystemPackage" }, "Task": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "status": { "type": "string" }, "exit_code": { "type": [ "integer", "null" ], "description": "set when the task has finished" }, "error": { "type": [ "string", "null" ] }, "started_at": { "type": [ "string", "null" ] }, "finished_at": { "type": [ "string", "null" ] }, "queued_at": { "type": [ "string", "null" ] }, "log": { "type": "string" }, "args": { "type": [ "string", "null" ] }, "resource": { "type": [ "string", "null" ], "description": "path under /api/v2 for the related resource" } }, "required": [ "id", "kind", "status", "exit_code", "error", "started_at", "finished_at", "queued_at", "log", "args", "resource" ], "title": "Task" }, "TransferFilesRequest": { "type": "object", "description": "Body of `copyFiles` and `moveFiles` (E34 batch 5 spec §4.2).", "properties": { "paths": { "type": "array", "description": "Entries relative to the home directory.", "items": { "type": "string" }, "minItems": 1, "maxItems": 1000, "uniqueItems": true }, "destination": { "type": [ "string", "null" ], "description": "Folder relative to the home directory; empty or null for the home directory." }, "on_conflict": { "type": "string", "description": "A name that exists in the destination: `fail` (default; `409` with `conflicts`), `skip`, `overwrite` or `rename` (first free \"name (n).ext\").", "enum": [ "fail", "skip", "overwrite", "rename" ] } }, "required": [ "paths", "destination" ], "title": "TransferFilesRequest" }, "UpdateAppProcessRequest": { "type": "object", "properties": { "start": { "type": "string", "pattern": "^[^\\x00-\\x1f\\x7f]{1,2048}$", "maxLength": 2048 }, "cwd": { "type": "string", "pattern": "^(\\.|[A-Za-z0-9_][A-Za-z0-9._\\/@+-]{0,199})$" }, "memory_mb": { "type": "integer", "minimum": 32, "maximum": 999999 }, "cpus": { "type": "string", "pattern": "^\\d{1,2}(\\.\\d{1,2})?$" } }, "title": "UpdateAppProcessRequest" }, "UpdateCronJobRequest": { "type": "object", "description": "PATCH /users/{user}/cron-jobs/{id}. Fields left out keep their value.", "properties": { "schedule": { "type": "string", "maxLength": 640 }, "command": { "type": "string", "maxLength": 4096 } }, "title": "UpdateCronJobRequest" }, "UpdateDatabaseRequest": { "type": "object", "description": "PATCH /users/{user}/databases/{database}. The user name is the short name.", "properties": { "db_user": { "type": "string", "pattern": "^[A-Za-z0-9_]+$", "maxLength": 32 } }, "required": [ "db_user" ], "title": "UpdateDatabaseRequest" }, "UpdateDnsRecordRequest": { "type": "object", "description": "PATCH /users/{user}/dns-zones/{domain}/records/{id}. The id does not change.\nFields left out keep their value.", "properties": { "name": { "type": "string", "maxLength": 253 }, "type": { "type": "string", "enum": [ "A", "AAAA", "CAA", "CNAME", "DNSKEY", "DS", "IPSECKEY", "KEY", "MX", "NS", "PTR", "SPF", "SRV", "TLSA", "TXT" ] }, "value": { "type": "string", "maxLength": 4096 }, "priority": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 65535 }, "ttl": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 2147483647 } }, "title": "UpdateDnsRecordRequest" }, "UpdateDnsZoneRequest": { "type": "object", "description": "PATCH /users/{user}/dns-zones/{domain}. Fields left out keep their value.\n`soa` can only be changed here.", "properties": { "ip": { "type": "string" }, "template": { "type": [ "string", "null" ], "pattern": "^[\\w.-]*$", "maxLength": 100 }, "ttl": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "soa": { "type": "string", "description": "The SOA record.", "pattern": "^[\\pL\\pN._-]+$", "maxLength": 253 }, "expiry": { "type": "string", "format": "date" }, "dnssec": { "type": "boolean" } }, "title": "UpdateDnsZoneRequest" }, "UpdateFirewallRuleRequest": { "type": "object", "description": "PATCH /system/firewall/rules/{rule} (E34 batch 6 spec §5.3): the fields of\nStoreFirewallRuleRequest, each optional; fields left out keep their value.", "properties": { "action": { "type": "string", "enum": [ "DROP", "ACCEPT" ] }, "protocol": { "type": "string", "enum": [ "TCP", "UDP", "ICMP" ] }, "port": { "type": "string", "maxLength": 255 }, "source": { "type": "string", "maxLength": 255 }, "comment": { "type": [ "string", "null" ], "maxLength": 255 } }, "title": "UpdateFirewallRuleRequest" }, "UpdateIpRequest": { "type": "object", "description": "PATCH /system/ips/{ip} (E34 batch 6 spec §5.2): fields left out keep\ntheir value; a null or empty `name` or `nat` removes it. The controller\nchecks that `owner` is an account.", "properties": { "owner": { "type": "string", "maxLength": 64 }, "shared": { "type": "boolean" }, "name": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9.-]*$", "maxLength": 255 }, "nat": { "type": [ "string", "null" ] } }, "title": "UpdateIpRequest" }, "UpdateMailAccountRequest": { "type": "object", "description": "PATCH /users/{user}/mail-domains/{domain}/accounts/{account}.\nOnly the tabs whose fields are sent are planned.", "properties": { "quota_mb": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 999999 }, "aliases": { "type": "array", "items": { "type": "string", "pattern": "^[\\w.-]+$", "maxLength": 64 } }, "forwards": { "type": "array", "items": { "type": "string", "pattern": "^[\\w.+-]+@[\\w.-]+$", "maxLength": 255 } }, "forward_only": { "type": "boolean" }, "discard_all": { "type": "boolean", "description": "Discard incoming mail. Refused together with forwards." }, "autoreply": { "type": [ "string", "null" ], "description": "The autoreply text, or null to turn it off.", "maxLength": 4000 }, "rate_limit": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 999999 } }, "title": "UpdateMailAccountRequest" }, "UpdateMailDomainRequest": { "type": "object", "description": "PATCH /users/{user}/mail-domains/{domain}. Fields left out keep their value.", "properties": { "antispam": { "type": "boolean" }, "antivirus": { "type": "boolean" }, "dkim": { "type": "boolean" }, "reject": { "type": "boolean" }, "catchall": { "type": [ "string", "null" ], "description": "An address, or null to deliver nothing for unknown accounts.", "pattern": "^[\\w.+-]+@[\\w.-]+$", "maxLength": 255 }, "webmail": { "type": [ "string", "null" ], "description": "A webmail client the server has, or null to turn webmail off.", "pattern": "^[\\w.-]+$", "maxLength": 64 }, "rate_limit": { "type": [ "integer", "null" ], "description": "Messages per hour. Administrators only.", "minimum": 1, "maximum": 999999 } }, "title": "UpdateMailDomainRequest" }, "UpdateNodeAppRequest": { "type": "object", "properties": { "start": { "type": "string", "pattern": "^(npm:[A-Za-z0-9][A-Za-z0-9:._-]{0,63}|[A-Za-z0-9_][A-Za-z0-9._\\/@+-]{0,199})$", "maxLength": 200 }, "cwd": { "type": "string", "pattern": "^(\\.|[A-Za-z0-9_][A-Za-z0-9._\\/@+-]{0,199})$" }, "version": { "type": "string", "pattern": "^(default|\\d{1,3}\\.\\d{1,3}\\.\\d{1,3})$" }, "instances": { "type": "integer", "minimum": 1, "maximum": 999 }, "memory_mb": { "type": "integer", "minimum": 64, "maximum": 999999 } }, "title": "UpdateNodeAppRequest" }, "UpdatePackageRequest": { "type": "object", "description": "PATCH /packages/{package}: the fields left out keep their value.", "properties": { "name": { "type": "string", "pattern": "^[[:alnum:]][-.\\w]*$", "maxLength": 60 }, "templates": { "type": "object", "properties": { "web": { "type": "string", "pattern": "^[[:alnum:]][-.\\w]*$", "maxLength": 100 }, "backend": { "type": "string", "pattern": "^[[:alnum:]][-.\\w]*$", "maxLength": 100 }, "proxy": { "type": "string", "pattern": "^[[:alnum:]][-.\\w]*$", "maxLength": 100 }, "dns": { "type": "string", "pattern": "^[[:alnum:]][-.\\w]*$", "maxLength": 100 } } }, "limits": { "type": "object", "properties": { "rate_limit": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "backups": { "type": "integer", "minimum": 0, "maximum": 1000 }, "web_domains": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100000000 }, "web_aliases": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100000000 }, "dns_domains": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100000000 }, "dns_records": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100000000 }, "mail_domains": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100000000 }, "mail_accounts": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100000000 }, "databases": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100000000 }, "cron_jobs": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100000000 }, "disk_mb": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100000000 }, "bandwidth_mb": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100000000 } } }, "resources": { "type": "object", "properties": { "cpu_quota": { "type": [ "string", "null" ], "pattern": "^\\d+(%|ms|s|[KMGT])?$", "maxLength": 20 }, "cpu_quota_period": { "type": [ "string", "null" ], "pattern": "^\\d+(%|ms|s|[KMGT])?$", "maxLength": 20 }, "memory_limit": { "type": [ "string", "null" ], "pattern": "^\\d+(%|ms|s|[KMGT])?$", "maxLength": 20 }, "swap_limit": { "type": [ "string", "null" ], "pattern": "^\\d+(%|ms|s|[KMGT])?$", "maxLength": 20 } } }, "shell": { "type": "string", "pattern": "^[[:alnum:]][-.\\w]*$", "maxLength": 100 }, "nameservers": { "type": "array", "items": { "type": "string", "pattern": "^([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z0-9-]+$", "maxLength": 253 }, "minItems": 2, "maxItems": 10 }, "backups_incremental": { "type": "boolean" }, "reseller": { "type": "object", "properties": { "users": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100000 }, "packages": { "type": "array", "items": { "type": "string", "pattern": "^(\\*|[[:alnum:]][-.\\w]*)$", "maxLength": 100 } }, "visible": { "type": "boolean" } } }, "ports": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 65535 }, "node": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "versions": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 999 }, "allowed": { "type": "string", "pattern": "^(lts|\\*|\\d{1,3}(,\\d{1,3})*)$", "maxLength": 100 }, "apps": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 999 } } }, "docker": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "apps": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 999 }, "cpus": { "type": [ "string", "null" ], "pattern": "^\\d{1,3}(\\.\\d{1,2})?$", "maxLength": 20 }, "memory": { "type": [ "string", "null" ], "pattern": "^\\d{1,7}[MG]?$", "maxLength": 20 } } }, "app_processes": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "max": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 999 }, "memory": { "type": [ "string", "null" ], "pattern": "^\\d{1,7}[MG]?$", "maxLength": 20 }, "cpus": { "type": [ "string", "null" ], "pattern": "^\\d{1,2}(\\.\\d{1,2})?$", "maxLength": 20 } } }, "php": { "type": "object", "properties": { "versions": { "type": "string", "pattern": "^(\\*|\\d{1,2}\\.\\d{1,2}(,\\d{1,2}\\.\\d{1,2})*)$", "maxLength": 200 }, "profiles": { "type": "string", "pattern": "^(\\*|[a-z0-9][a-z0-9-]{0,31}(,[a-z0-9][a-z0-9-]{0,31})*)$", "maxLength": 500 }, "default_profile": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,31}$" } } } }, "title": "UpdatePackageRequest" }, "UpdatePhpIniValuesRequest": { "type": "object", "description": "PATCH /system/php/versions/{php}/ini/{sapi} (E41 §6.2, §9): directives of\nthe php.ini form.", "properties": { "values": { "type": "object", "description": "Directives of the form and their new values, for example\n`{\"memory_limit\": \"256M\", \"display_errors\": false}`. Switches take\nbooleans, `disable_functions` a list of function names.", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "boolean" }, { "type": "array", "items": { "type": "string" } } ] } } }, "required": [ "values" ], "title": "UpdatePhpIniValuesRequest" }, "UpdateServerSettingsRequest": { "type": "object", "description": "PATCH /system/settings/{tab} (E34 batch 6 spec §5.7, D58): the fields of\none tab, each optional; fields left out keep their value. Before any\nvalidation, in this order: administrators only (`403`), a tab whose system\nis not installed `404`, the read-only `dns` tab `403`, a field the API\nnever changes (the API switches and the protection group of D58,\nphpMyAdmin single sign-on and the logo of D23) `403` naming it, a field\nthe tab does not take `422`.", "properties": { "hostname": { "type": "string", "pattern": "^[A-Za-z0-9]([A-Za-z0-9-]{0,61}[A-Za-z0-9])?(\\.[A-Za-z0-9]([A-Za-z0-9-]{0,61}[A-Za-z0-9])?)*$", "maxLength": 253 }, "timezone": { "type": "string", "pattern": "^[A-Za-z0-9_+\\-\\/]+$", "maxLength": 64 }, "language": { "type": "string", "pattern": "^[a-z]{2,3}(-[a-z]{2})?$", "maxLength": 10 }, "language_all": { "type": "boolean" }, "theme": { "type": "string", "pattern": "^[\\w-]+$", "maxLength": 64 }, "user_theme": { "type": "boolean" }, "debug": { "type": "boolean" }, "experimental": { "type": "boolean" }, "php_default": { "type": "string", "pattern": "^\\d\\.\\d$" }, "webmail_alias": { "type": "string", "pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?$", "maxLength": 63 }, "webmail_port": { "type": [ "integer", "null" ], "minimum": 1024, "maximum": 65535 }, "webmail_link": { "type": "string", "enum": [ "port", "domain" ] }, "relay": { "type": "boolean" }, "relay_host": { "type": "string", "pattern": "^[A-Za-z0-9.-]+$", "maxLength": 253 }, "relay_port": { "type": "integer", "minimum": 1, "maximum": 65535 }, "relay_user": { "type": [ "string", "null" ], "maxLength": 128 }, "relay_password": { "type": "string", "maxLength": 256 }, "pma_alias": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$", "maxLength": 63 }, "pga_alias": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$", "maxLength": 63 }, "db_admin_port": { "type": [ "integer", "null" ], "minimum": 1024, "maximum": 65535 }, "local": { "type": "boolean" }, "mode": { "type": "string", "enum": [ "gzip", "zstd" ] }, "level": { "type": "integer", "minimum": 1, "maximum": 19 }, "remote": { "type": "boolean" }, "remote_type": { "type": "string", "enum": [ "ftp", "sftp", "b2", "rclone" ] }, "host": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9.:_-]+$", "maxLength": 253 }, "port": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 65535 }, "username": { "type": [ "string", "null" ], "maxLength": 128 }, "password": { "type": "string", "maxLength": 4096 }, "path": { "type": [ "string", "null" ], "pattern": "^[\\w\\/.:@~+-]*$", "maxLength": 255 }, "bucket": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9-]+$", "maxLength": 63 }, "key_id": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9]+$", "maxLength": 128 }, "incremental": { "type": "boolean" }, "repo": { "type": "string", "maxLength": 1024 }, "snapshots": { "type": "integer", "minimum": -1, "maximum": 9999 }, "keep_daily": { "type": "integer", "minimum": -1, "maximum": 9999 }, "keep_weekly": { "type": "integer", "minimum": -1, "maximum": 9999 }, "keep_monthly": { "type": "integer", "minimum": -1, "maximum": 9999 }, "keep_yearly": { "type": "integer", "minimum": -1, "maximum": 9999 }, "certificate": { "type": "string", "pattern": "-----BEGIN CERTIFICATE-----", "maxLength": 65536 }, "key": { "type": "string", "pattern": "-----BEGIN [A-Z ]*PRIVATE KEY-----", "maxLength": 65536 }, "LOGIN_STYLE": { "type": "string", "enum": [ "default", "old" ] }, "INACTIVE_SESSION_TIMEOUT": { "type": "integer", "minimum": 1, "maximum": 1440 }, "POLICY_CSRF_STRICTNESS": { "type": "string", "enum": [ "0", "1", "2" ] }, "POLICY_SYSTEM_PASSWORD_RESET": { "type": "string", "enum": [ "yes", "no" ] }, "POLICY_USER_EDIT_DETAILS": { "type": "string", "enum": [ "yes", "no" ] }, "POLICY_USER_EDIT_WEB_TEMPLATES": { "type": "string", "enum": [ "yes", "no" ] }, "POLICY_USER_EDIT_DNS_TEMPLATES": { "type": "string", "enum": [ "yes", "no" ] }, "POLICY_USER_VIEW_LOGS": { "type": "string", "enum": [ "yes", "no" ] }, "POLICY_USER_DELETE_LOGS": { "type": "string", "enum": [ "yes", "no" ] }, "POLICY_USER_VIEW_SUSPENDED": { "type": "string", "enum": [ "yes", "no" ] }, "POLICY_BACKUP_SUSPENDED_USERS": { "type": "string", "enum": [ "yes", "no" ] }, "POLICY_SYNC_ERROR_DOCUMENTS": { "type": "string", "enum": [ "yes", "no" ] }, "POLICY_SYNC_SKELETON": { "type": "string", "enum": [ "yes", "no" ] }, "ENFORCE_SUBDOMAIN_OWNERSHIP": { "type": "string", "enum": [ "yes", "no" ] }, "POLICY_RESELLER_PACKAGE_SHELLS": { "type": "string", "pattern": "^[\\w.-]+(,[\\w.-]+)*$", "maxLength": 255 }, "app_installer": { "type": "boolean" }, "APP_NAME": { "type": "string", "minLength": 1, "maxLength": 255 }, "TITLE": { "type": "string", "minLength": 1, "maxLength": 255 }, "SUBJECT_EMAIL": { "type": "string", "minLength": 1, "maxLength": 255 }, "FROM_NAME": { "type": [ "string", "null" ], "maxLength": 255 }, "FROM_EMAIL": { "type": [ "string", "null" ], "format": "email", "maxLength": 254 }, "HIDE_DOCS": { "type": "string", "enum": [ "yes", "no" ] } }, "title": "UpdateServerSettingsRequest" }, "UpdateSettings": { "type": "object", "properties": { "auto_update": { "type": "boolean", "description": "the panel packages are updated every day" }, "send_email": { "type": "boolean", "description": "the administrator gets an e-mail after an update" }, "send_log": { "type": "boolean", "description": "that e-mail carries the log of the update" } }, "required": [ "auto_update", "send_email", "send_log" ], "title": "UpdateSettings" }, "UpdateUserRequest": { "type": "object", "description": "PATCH /users/{user}: the General tab without the password (PUT\n/users/{user}/password), and the Name servers, Security and\nAdministration tabs (E34 batch 6 D63); fields left out keep their value.", "properties": { "name": { "type": "string", "description": "The full name.", "maxLength": 100 }, "email": { "type": "string", "format": "email", "maxLength": 254 }, "language": { "type": "string", "pattern": "^[a-z]{2,3}(-[a-z]{2})?$", "maxLength": 10 }, "nameservers": { "type": "array", "description": "2 to 8 host names. Administrators and resellers for their customers, an administrator for itself.", "items": { "type": "string", "pattern": "^([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z0-9-]+$", "maxLength": 253 }, "minItems": 2, "maxItems": 8 }, "allowed_ips": { "type": [ "array", "null" ], "description": "The IPv4 addresses the login is allowed from, compared exactly (the user record takes no networks and no IPv6); null drops the restriction.", "items": { "type": "string" }, "minItems": 1, "maxItems": 24, "uniqueItems": true }, "login_disabled": { "type": "boolean", "description": "Administrators, not for their own account." }, "role": { "description": "Administrators, never for the root administrator or themselves.", "$ref": "#/components/schemas/ApiRole" }, "owner": { "type": "string", "description": "Administrators: the root administrator or a reseller that owns a user.", "pattern": "^[[:alnum:]][-.\\w]*$", "maxLength": 32 }, "shell": { "type": "string", "description": "Administrators: a shell installed on the server (`nologin` without SSH).", "pattern": "^[[:alnum:]][-.\\w]*$", "maxLength": 32 }, "php_cli": { "type": "string", "description": "Administrators: a PHP version installed on the server, for the command line.", "pattern": "^\\d+\\.\\d+$", "maxLength": 10 } }, "title": "UpdateUserRequest" }, "UpdateUserSecretRequest": { "type": "object", "description": "PATCH /users/{user}/secrets/{name}: the description of a secret (E38).", "properties": { "description": { "type": [ "string", "null" ], "description": "At most 255 characters, without quotes, `$`, backquote, backslash or `|`; empty removes it.", "maxLength": 255 } }, "required": [ "description" ], "title": "UpdateUserSecretRequest" }, "UpdateWebDomainRequest": { "type": "object", "description": "PATCH /users/{user}/web-domains/{domain}: the fields of the General tab\n(IP address, document root) and of the Advanced tab; the fields left out\nkeep their value. Aliases have their own operations.", "properties": { "ip": { "type": "string", "description": "One of the user's addresses (v-list-user-ips)." }, "custom_document_root": { "type": [ "object", "null" ], "description": "Serve the folder of another domain of the user; null serves the domain's own public_html.", "properties": { "domain": { "type": "string", "pattern": "^[\\pL\\pN.-]+$", "maxLength": 253 }, "folder": { "type": [ "string", "null" ], "description": "A folder below that domain's public_html.", "pattern": "^[\\pL\\pN\\/._ -]*$", "maxLength": 255 } } }, "templates": { "type": "object", "properties": { "web": { "type": "string", "description": "A web template of the server (v-list-web-templates).", "pattern": "^[\\w.-]+$", "maxLength": 100 }, "backend": { "type": "string", "description": "A PHP-FPM backend template, on servers with a backend.", "pattern": "^[\\w.-]+$", "maxLength": 100 }, "proxy": { "type": "string", "description": "A proxy template, on servers with a proxy; it also turns the proxy on.", "pattern": "^[\\w.-]+$", "maxLength": 100 } } }, "proxy": { "type": "boolean", "description": "Turns the proxy in front of the web server on or off." }, "proxy_extensions": { "type": "array", "description": "Extensions the proxy serves itself.", "items": { "type": "string", "pattern": "^[\\w.-]+$", "maxLength": 20 }, "maxItems": 200 }, "fastcgi_cache": { "type": "object", "description": "The NGINX FastCGI cache, on servers where NGINX runs PHP-FPM.", "properties": { "enabled": { "type": "boolean" }, "duration": { "type": [ "string", "null" ], "description": "How long a page is kept, such as 2m (the default), 1h or 1d.", "pattern": "^\\d+[smhd]$" } } }, "backend_port": { "type": [ "string", "null" ], "description": "`auto` or a port of the owner's pool, for a template that takes an app port (E6).", "pattern": "^(auto|\\d{1,5})$" } }, "title": "UpdateWebDomainRequest" }, "User": { "type": "object", "properties": { "username": { "type": "string", "description": "the login name" }, "name": { "type": "string", "description": "the full name" }, "email": { "type": "string", "description": "the contact e-mail" }, "role": { "$ref": "#/components/schemas/ApiRole" }, "owner": { "type": [ "string", "null" ], "description": "the reseller or administrator that owns the user; null for administrators" }, "package": { "type": "string" }, "language": { "type": "string" }, "shell": { "type": "string", "description": "the login shell (nologin without SSH)" }, "suspended": { "type": "boolean" }, "login_disabled": { "type": "boolean" }, "two_factor": { "type": "boolean" }, "nameservers": { "type": "array", "items": { "type": "string" } }, "allowed_ips": { "type": [ "array", "null" ], "description": "the addresses or networks the login is allowed from; null without a restriction", "items": { "type": "string" } }, "php_cli": { "type": [ "string", "null" ], "description": "the PHP version of the command line; null for the server's default" }, "limits": { "type": "object", "properties": { "web_domains": { "type": [ "integer", "null" ] }, "dns_domains": { "type": [ "integer", "null" ] }, "mail_domains": { "type": [ "integer", "null" ] }, "mail_accounts": { "type": [ "integer", "null" ] }, "databases": { "type": [ "integer", "null" ] }, "cron_jobs": { "type": [ "integer", "null" ] }, "disk_mb": { "type": [ "integer", "null" ] }, "bandwidth_mb": { "type": [ "integer", "null" ] } }, "required": [ "web_domains", "dns_domains", "mail_domains", "mail_accounts", "databases", "cron_jobs", "disk_mb", "bandwidth_mb" ] }, "usage": { "type": "object", "properties": { "web_domains": { "type": "integer" }, "dns_domains": { "type": "integer" }, "mail_domains": { "type": "integer" }, "mail_accounts": { "type": "integer" }, "databases": { "type": "integer" }, "cron_jobs": { "type": "integer" }, "disk_mb": { "type": "integer" }, "bandwidth_mb": { "type": "integer" } }, "required": [ "web_domains", "dns_domains", "mail_domains", "mail_accounts", "databases", "cron_jobs", "disk_mb", "bandwidth_mb" ] }, "created_at": { "type": [ "string", "null" ], "description": "creation time in the server's time zone, YYYY-MM-DDTHH:MM:SS" } }, "required": [ "username", "name", "email", "role", "owner", "package", "language", "shell", "suspended", "login_disabled", "two_factor", "nameservers", "allowed_ips", "php_cli", "limits", "usage", "created_at" ], "title": "User" }, "UserPackageRequest": { "type": "object", "description": "PUT /users/{user}/package", "properties": { "package": { "type": "string", "description": "A package the caller may assign (see GET /packages).", "pattern": "^[[:alnum:]][-.\\w]*$", "maxLength": 100 } }, "required": [ "package" ], "title": "UserPackageRequest" }, "UserPasswordRequest": { "type": "object", "description": "PUT /users/{user}/password", "properties": { "password": { "type": "string", "description": "At least 8 characters with a lower-case and an upper-case letter and a digit.", "pattern": "\\d", "minLength": 8, "maxLength": 256 } }, "required": [ "password" ], "title": "UserPasswordRequest" }, "UserSecret": { "type": "object", "properties": { "name": { "type": "string", "description": "the path name, for example `/shop/db_password`" }, "description": { "type": "string" }, "version": { "type": "integer", "description": "the current version" }, "fingerprint": { "type": "string", "description": "8 hex characters of a keyed hash of the value: equal values of one user have equal fingerprints" }, "reference": { "type": "string", "description": "what an app environment writes to use the secret" }, "updated_at": { "type": "string", "description": "date and time of the current version, server time" }, "versions": { "type": "array", "items": {} }, "used_by": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } }, "required": [ "type", "id" ] } }, "used_by_count": { "type": "integer" } }, "required": [ "name", "description", "version", "fingerprint", "reference", "updated_at", "versions", "used_by", "used_by_count" ], "title": "UserSecret" }, "WebDomain": { "type": "object", "properties": { "domain": { "type": "string" }, "user": { "type": "string", "description": "the owner" }, "ip": { "type": "string", "description": "the server address the domain is bound to (without its NAT address)" }, "aliases": { "type": "array", "items": { "type": "string" } }, "document_root": { "type": "string", "description": "the folder the domain serves" }, "custom_document_root": { "type": [ "object", "null" ], "description": "The folder of another domain of the same user that this domain serves; null for its own public_html.", "properties": { "domain": { "type": "string" }, "folder": { "type": "string", "description": "a folder below its public_html, '' for public_html itself" } }, "required": [ "domain", "folder" ] }, "templates": { "type": "object", "properties": { "web": { "type": "string" }, "backend": { "type": [ "string", "null" ], "description": "null without a PHP-FPM backend" }, "proxy": { "type": [ "string", "null" ], "description": "null with the proxy off" } }, "required": [ "web", "backend", "proxy" ] }, "proxy_extensions": { "type": "array", "description": "extensions the proxy serves itself", "items": { "type": "string" } }, "fastcgi_cache": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "duration": { "type": [ "string", "null" ], "description": "how long NGINX keeps a page, such as 2m" } }, "required": [ "enabled", "duration" ] }, "ssl": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "letsencrypt": { "type": "boolean", "description": "the certificate comes from Let's Encrypt" }, "force": { "type": "boolean", "description": "HTTP is redirected to HTTPS" }, "hsts": { "type": "boolean" }, "home": { "type": "string", "description": "public_html for HTTP and HTTPS, or private/ for HTTPS", "enum": [ "same", "single" ] }, "key_algorithm": { "type": "string", "description": "the key type of a Let's Encrypt certificate", "enum": [ "ecdsa-256", "ecdsa-384", "rsa" ] }, "certificate": { "type": [ "object", "null" ], "description": "The installed certificate, null without SSL; only part of a single domain.", "properties": { "subject": { "type": "string" }, "names": { "type": "array", "description": "the names it covers", "items": { "type": "string" } }, "issuer": { "type": "string" }, "not_before": { "type": [ "string", "null" ], "description": "start of validity, UTC, YYYY-MM-DDTHH:MM:SSZ" }, "not_after": { "type": [ "string", "null" ], "description": "end of validity, UTC, YYYY-MM-DDTHH:MM:SSZ" } }, "required": [ "subject", "names", "issuer", "not_before", "not_after" ] } }, "required": [ "enabled", "letsencrypt", "force", "hsts", "home", "key_algorithm" ] }, "redirect": { "type": [ "object", "null" ], "description": "Where every request is redirected; null without a redirect.", "properties": { "url": { "type": "string" }, "code": { "type": "integer" } }, "required": [ "url", "code" ] }, "stats": { "type": [ "string", "null" ], "description": "the statistics engine, null without statistics" }, "ftp_accounts": { "type": "array", "items": { "type": "object", "properties": { "username": { "type": "string" }, "path": { "type": "string" } }, "required": [ "username", "path" ] } }, "suspended": { "type": "boolean" }, "disk_mb": { "type": "integer" }, "bandwidth_mb": { "type": "integer" }, "backend_port": { "type": [ "integer", "null" ], "description": "the app port of the domain's template (E6); null when the template takes none" }, "created_at": { "type": [ "string", "null" ], "description": "creation time in the server's time zone, YYYY-MM-DDTHH:MM:SS" } }, "required": [ "domain", "user", "ip", "aliases", "document_root", "custom_document_root", "templates", "proxy_extensions", "fastcgi_cache", "ssl", "redirect", "stats", "ftp_accounts", "suspended", "disk_mb", "bandwidth_mb", "created_at" ], "title": "WebDomain" }, "WebDomainAliasRequest": { "type": "object", "description": "POST /users/{user}/web-domains/{domain}/aliases: one more name of the domain, lowercased.", "properties": { "alias": { "type": "string", "description": "A host name such as www.example.com, or a wildcard such as *.example.com.", "pattern": "^(\\*\\.)?[\\pL\\pN]([\\pL\\pN_-]*[\\pL\\pN])?(\\.[\\pL\\pN]([\\pL\\pN_-]*[\\pL\\pN])?)+$", "maxLength": 253 } }, "required": [ "alias" ], "title": "WebDomainAliasRequest" }, "WebDomainLogMeta": { "type": "object", "description": "The log that was read and the number of lines asked for (E37 spec §4.1).", "properties": { "type": { "type": "string", "enum": [ "error", "access" ] }, "lines": { "type": "integer", "minimum": 1, "maximum": 1000 } }, "required": [ "type", "lines" ] }, "WebDomainPhp": { "type": "object", "properties": { "version": { "type": [ "string", "null" ], "description": "the PHP version; null for a domain without PHP (`no-php`)" }, "backend_template": { "type": "string", "description": "the backend template" }, "profile": { "type": "string", "description": "the PHP-FPM profile of the pool" }, "profile_applied": { "type": "boolean", "description": "false when the backend template has no profile line, so the pool keeps its own settings" }, "allowed": { "type": "object", "description": "Whether the package allows the domain's version and profile; a\nvalue the package no longer allows stays but cannot be chosen again.", "properties": { "version": { "type": "boolean" }, "profile": { "type": "boolean" } }, "required": [ "version", "profile" ] }, "package": { "type": "string", "description": "the package of the owner" }, "default_profile": { "type": "string", "description": "the profile of new web domains of the package" }, "versions": { "type": "array", "description": "installed versions the package allows", "items": { "type": "object", "properties": { "version": { "type": "string" }, "status": { "type": "string" }, "eol": { "type": [ "string", "null" ] } }, "required": [ "version", "status", "eol" ] } }, "profiles": { "type": "array", "description": "profiles the package allows", "items": { "type": "string" } }, "effective": { "type": "object", "description": "memory_limit, upload_max_filesize, post_max_size, max_execution_time and max_input_vars\nwith their source: `profile` or `php.ini`.", "additionalProperties": { "type": "object", "properties": { "value": { "type": [ "string", "null" ] }, "source": { "type": "string" } }, "required": [ "value", "source" ] } } }, "required": [ "version", "backend_template", "profile", "profile_applied", "allowed", "package", "default_profile", "versions", "profiles", "effective" ], "title": "WebDomainPhp" }, "WebDomainSslRequest": { "type": "object", "description": "PUT /users/{user}/web-domains/{domain}/ssl: an uploaded certificate, or\nforced HTTPS and HSTS alone for the certificate the domain has.", "properties": { "certificate": { "type": [ "string", "null" ], "description": "The certificate (PEM); left out, the domain keeps its certificate, Let's Encrypt included.", "maxLength": 65536 }, "key": { "type": [ "string", "null" ], "description": "Its private key (PEM); required with a first certificate, left out it keeps the current key.", "maxLength": 65536 }, "ca": { "type": [ "string", "null" ], "description": "The intermediate certificates (PEM).", "maxLength": 65536 }, "force": { "type": "boolean", "description": "Redirect HTTP to HTTPS; left out it keeps its value." }, "hsts": { "type": "boolean", "description": "Send Strict-Transport-Security; left out it keeps its value." } }, "title": "WebDomainSslRequest" }, "WebSettings": { "type": "object", "description": "The `web` tab of the server settings.", "properties": { "web_system": { "type": [ "string", "null" ], "description": "Read-only." }, "proxy_system": { "type": [ "string", "null" ], "description": "Read-only." }, "backend": { "type": [ "string", "null" ], "description": "Read-only." }, "php_default": { "type": [ "string", "null" ] }, "php_versions": { "type": "array", "items": { "$ref": "#/components/schemas/PhpVersion" } } }, "required": [ "web_system", "proxy_system", "backend", "php_default", "php_versions" ] }, "WhiteLabelSettings": { "type": "object", "description": "The `white-label` tab of the server settings.", "properties": { "APP_NAME": { "type": "string" }, "TITLE": { "type": "string" }, "SUBJECT_EMAIL": { "type": "string" }, "FROM_NAME": { "type": "string" }, "FROM_EMAIL": { "type": "string" }, "HIDE_DOCS": { "type": "string" }, "custom_logo": { "type": "boolean", "description": "Read-only through the API (403 on a change)." } }, "required": [ "APP_NAME", "TITLE", "SUBJECT_EMAIL", "FROM_NAME", "FROM_EMAIL", "HIDE_DOCS", "custom_logo" ] } }, "responses": { "Unauthenticated": { "description": "The access key is missing, unknown or wrong (`E_UNAUTHENTICATED`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "The API is off for this key (`E_API_DISABLED`), the role or a permission set refuses the call (`E_FORBIDDEN`), or the owner is suspended (`E_SUSPENDED`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "No such object in the scope of the key (`E_NOTEXIST`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Gone": { "description": "The task result is no longer kept (`E_GONE`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Conflict": { "description": "The object exists or is in use (`E_EXISTS`, `E_INUSE`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "TooLarge": { "description": "The file or the content is larger than the limit of the operation (`E_LIMIT`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ValidationFailed": { "description": "The request is invalid (`E_VALIDATION` with `fields`, or a command refused an argument), or a package limit is reached (`E_LIMIT`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "TooManyRequests": { "description": "Too many requests (`E_RATE_LIMIT`); `Retry-After` names the seconds to wait.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ServerError": { "description": "A command failed on the server.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unavailable": { "description": "The service is disabled or the server is too busy (`E_DISABLED`, `E_LA`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "InsufficientStorage": { "description": "The panel has too little space to stage the data now (`E_DISK`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ArcPanel-Version": { "$ref": "#/components/headers/Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "securitySchemes": { "accessKey": { "type": "http", "scheme": "bearer", "bearerFormat": "ACCESS_KEY_ID:SECRET_ACCESS_KEY", "description": "An access key of the panel and its secret, joined by a colon." } }, "headers": { "RequestId": { "description": "The id of the request: the client's X-Request-Id, or a new one.", "schema": { "type": "string" } }, "Version": { "description": "Version of the panel.", "schema": { "type": "string" } }, "RetryAfter": { "description": "Seconds to wait before the next request.", "schema": { "type": "integer" } }, "Location": { "description": "URL of the resource (201) or of the resource to poll (202).", "schema": { "type": "string" } }, "Link": { "description": "Task monitor URL (`rel=\"monitor\"`) for `GET /tasks/{id}`.", "schema": { "type": "string" } } } }, "security": [ { "accessKey": [] } ] }