{ "openapi": "3.1.0", "info": { "title": "HF Panel API", "version": "v1", "description": "The HF Panel token API: hosting accounts and everything on them (domains, DNS, email, databases, SSL, backups, cron jobs, FTP, PHP, apps, Git, Docker, Redis, redirects), packages, resellers, the server, billing, tickets, webhooks and notifications. Answers are {\"ok\": true, \"data\": …} or {\"ok\": false, \"error\": \"…\"} (with X-HF-Errors: object: {\"ok\": false, \"error\": {\"code\": \"…\", \"message\": \"…\"}}). Lists have \"meta\" and take page, per_page, q and status; a created item's address is in the Location header." }, "servers": [ { "url": "https://api.yourdomain.com/v1", "description": "The API's own address" } ], "security": [ { "bearer": [] } ], "tags": [ { "name": "General" }, { "name": "Packages" }, { "name": "Accounts" }, { "name": "Domains" }, { "name": "Email" }, { "name": "Databases" }, { "name": "MongoDB" }, { "name": "Server" }, { "name": "Resellers" }, { "name": "SSL" }, { "name": "Backups" }, { "name": "SSH keys" }, { "name": "Apps" }, { "name": "Staging" }, { "name": "Site templates" }, { "name": "WordPress" }, { "name": "Status page" }, { "name": "Billing" }, { "name": "Support" }, { "name": "Team" }, { "name": "Abuse desk" }, { "name": "DNS" }, { "name": "Cron jobs" }, { "name": "FTP" }, { "name": "Uptime" }, { "name": "Firewall" }, { "name": "Staff" }, { "name": "Git" }, { "name": "Redis" }, { "name": "Memcached" }, { "name": "Docker" }, { "name": "Logs" }, { "name": "Node.js apps" }, { "name": "Python apps" }, { "name": "Ruby apps" }, { "name": "Firewall rules" }, { "name": "Redirects" }, { "name": "PHP" }, { "name": "Tickets" }, { "name": "Webhooks" }, { "name": "Notifications" }, { "name": "Partner licences", "description": "The publisher's licence server only: hosting companies with bulk licences manage them with a partner API key." } ], "paths": { "/me": { "get": { "operationId": "getMe", "tags": [ "General" ], "summary": "Who the token belongs to, and its access", "description": "Any token.", "parameters": [ { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/Me" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "username": "example", "email": "example", "role": "example", "two_factor": true, "token": {} } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "any", "x-hf-write": false } }, "/packages": { "get": { "operationId": "listPackages", "tags": [ "Packages" ], "summary": "The hosting packages, cheapest first", "description": "Administrator and reseller tokens.", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" }, "x-hf-generic": true }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" }, "x-hf-generic": true }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" }, "x-hf-generic": true }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" }, "x-hf-generic": true }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Package" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ { "id": 1, "name": "example", "disk_mb": 1, "max_domains": 1, "max_databases": 1, "max_mongo_databases": 1, "max_mailboxes": 1, "price_month": 1.5, "redis_mb": 1, "memcached_mb": 1 } ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "staff", "x-hf-write": false }, "post": { "operationId": "createPackage", "tags": [ "Packages" ], "summary": "Create a package", "description": "Administrator tokens only. Needs a \"Read & change\" token. Send an Idempotency-Key header to retry safely.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "the package's name (up to 40 characters)" }, "disk_mb": { "type": "integer", "description": "disk space in MB (stored in whole GB, rounded); 0 = no limit" }, "max_domains": { "type": "integer", "description": "domains; 0 = no limit" }, "max_databases": { "type": "integer", "description": "MySQL and PostgreSQL databases; 0 = no limit" }, "max_mongo_databases": { "type": "integer", "description": "MongoDB databases (0–1000)" }, "max_mailboxes": { "type": "integer", "description": "email accounts; 0 = no limit" }, "price_month": { "type": "number", "description": "monthly price" }, "cpu": { "type": "number", "description": "CPU cores (0.1 or more; 0 = no limit)" }, "memory_mb": { "type": "integer", "description": "memory in MB (128 or more; 0 = no limit)" }, "max_procs": { "type": "integer", "description": "processes (20 or more; 0 = no limit)" }, "redis_mb": { "type": "integer", "description": "Redis memory in MB (16–8192; 0 = none)" }, "memcached_mb": { "type": "integer", "description": "Memcached memory in MB (16–8192; 0 = none)" }, "mail_hour": { "type": "integer", "description": "emails sent per hour (0 = the server default)" }, "mail_day": { "type": "integer", "description": "emails sent per day (0 = the server default)" }, "max_docker": { "type": "integer", "description": "Docker apps (0–50)" }, "trial_days": { "type": "integer", "description": "free trial days (0–90)" }, "max_files": { "type": "integer", "description": "files (inodes); 0 = no limit" }, "team_members": { "type": "integer", "description": "team members (0 = unlimited, -1 = none, up to 100)" }, "webdisk_users": { "type": "integer", "description": "Web Disk logins (0–1000)" }, "io_mbps": { "type": "integer", "description": "disk speed in MB/s (5 or more; 0 = no limit)" }, "iops": { "type": "integer", "description": "disk operations per second (100 or more; 0 = no limit)" }, "feature_list": { "type": "integer", "description": "the feature list's id (0 = every feature)" }, "php_workers": { "type": "integer", "description": "PHP workers per website (0 = no limit)" }, "app_processes": { "type": "integer", "description": "processes per Node.js, Python or Ruby app (5 or more; 0 = no limit)" } }, "required": [ "name" ] }, "example": { "name": "example" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/Package" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "name": "example", "disk_mb": 1, "max_domains": 1, "max_databases": 1, "max_mongo_databases": 1, "max_mailboxes": 1, "price_month": 1.5, "redis_mb": 1, "memcached_mb": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": true } }, "/accounts": { "get": { "operationId": "listAccounts", "tags": [ "Accounts" ], "summary": "Every hosting account the token sees", "description": "Administrator and reseller tokens.", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" }, "x-hf-generic": true }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" }, "x-hf-generic": true }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" }, "x-hf-generic": true }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" }, "x-hf-generic": true }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Account" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ { "username": "example", "email": "example", "status": "example", "package": "example", "disk_used_mb": 1, "disk_limit_mb": 1, "domains": [], "two_factor": true, "server": "example", "created_at": "example", "last_login_at": "example" } ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "staff", "x-hf-write": false }, "post": { "operationId": "createAccount", "tags": [ "Accounts" ], "summary": "Create a hosting account", "description": "Administrator and reseller tokens. Needs a \"Read & change\" token. Send an Idempotency-Key header to retry safely.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "username": { "type": "string", "description": "3–16 lower-case letters and numbers" }, "email": { "type": "string", "description": "contact email" }, "package": { "type": "string", "description": "the package's name or id" }, "password": { "type": "string", "description": "empty = a random one, returned once" }, "domain": { "type": "string", "description": "the first website" }, "welcome": { "type": "boolean", "description": "email the welcome message" }, "server": { "type": "string", "description": "administrators: the server's name, or auto" } }, "required": [ "username", "email", "package" ] }, "example": { "username": "example", "email": "example", "package": "example" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "staff", "x-hf-write": true } }, "/accounts/{username}": { "get": { "operationId": "getAccount", "tags": [ "Accounts" ], "summary": "One hosting account", "description": "Administrator and reseller tokens.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/Account" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "username": "example", "email": "example", "status": "example", "package": "example", "disk_used_mb": 1, "disk_limit_mb": 1, "domains": [], "two_factor": true, "server": "example", "created_at": "example", "last_login_at": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "staff", "x-hf-write": false }, "delete": { "operationId": "deleteAccount", "tags": [ "Accounts" ], "summary": "Delete an account with everything in it", "description": "Administrator and reseller tokens. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "staff", "x-hf-write": true } }, "/accounts/{username}/suspend": { "post": { "operationId": "suspendAccount", "tags": [ "Accounts" ], "summary": "Suspend an account", "description": "Administrator and reseller tokens. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/Account" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "username": "example", "email": "example", "status": "example", "package": "example", "disk_used_mb": 1, "disk_limit_mb": 1, "domains": [], "two_factor": true, "server": "example", "created_at": "example", "last_login_at": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "staff", "x-hf-write": true } }, "/accounts/{username}/unsuspend": { "post": { "operationId": "unsuspendAccount", "tags": [ "Accounts" ], "summary": "Unsuspend an account", "description": "Administrator and reseller tokens. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/Account" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "username": "example", "email": "example", "status": "example", "package": "example", "disk_used_mb": 1, "disk_limit_mb": 1, "domains": [], "two_factor": true, "server": "example", "created_at": "example", "last_login_at": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "staff", "x-hf-write": true } }, "/accounts/{username}/package": { "post": { "operationId": "changeAccountPackage", "tags": [ "Accounts" ], "summary": "Move an account to another package", "description": "Administrator and reseller tokens. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "package": { "type": "string", "description": "the package's name or id" } }, "required": [ "package" ] }, "example": { "package": "example" } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/Account" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "username": "example", "email": "example", "status": "example", "package": "example", "disk_used_mb": 1, "disk_limit_mb": 1, "domains": [], "two_factor": true, "server": "example", "created_at": "example", "last_login_at": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "staff", "x-hf-write": true }, "put": { "operationId": "changeAccountPackagePut", "tags": [ "Accounts" ], "summary": "Move an account to another package", "description": "Administrator and reseller tokens. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "package": { "type": "string", "description": "the package's name or id" } }, "required": [ "package" ] }, "example": { "package": "example" } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/Account" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "username": "example", "email": "example", "status": "example", "package": "example", "disk_used_mb": 1, "disk_limit_mb": 1, "domains": [], "two_factor": true, "server": "example", "created_at": "example", "last_login_at": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "staff", "x-hf-write": true } }, "/accounts/{username}/password": { "post": { "operationId": "setAccountPassword", "tags": [ "Accounts" ], "summary": "Set the panel and SFTP password", "description": "Administrator and reseller tokens. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "password": { "type": "string", "description": "the new password" } }, "required": [ "password" ] }, "example": { "password": "example" } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "staff", "x-hf-write": true }, "put": { "operationId": "setAccountPasswordPut", "tags": [ "Accounts" ], "summary": "Set the panel and SFTP password", "description": "Administrator and reseller tokens. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "password": { "type": "string", "description": "the new password" } }, "required": [ "password" ] }, "example": { "password": "example" } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "staff", "x-hf-write": true } }, "/accounts/{username}/login": { "post": { "operationId": "createLoginLink", "tags": [ "Accounts" ], "summary": "A one-time sign-in link (2 minutes)", "description": "Administrator and reseller tokens. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "goto": { "type": "string", "description": "the screen to open" } } }, "example": { "goto": "example" } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "staff", "x-hf-write": true } }, "/accounts/{username}/usage": { "get": { "operationId": "getAccountUsage", "tags": [ "Accounts" ], "summary": "Disk, bandwidth, counts and resource usage against the limits", "description": "Administrator and reseller tokens.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "period", "in": "query", "required": false, "description": "the resource usage series: 24h (5-minute points, the default), 7d (hourly), 30d (4-hourly) or 1y (daily)", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/AccountUsage" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "username": "example", "disk_used_mb": 1, "disk_limit_mb": 1, "bandwidth_month_mb": 1, "domains": 1, "mailboxes": 1, "databases": 1, "mongo_databases": 1, "resources": {} } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "staff", "x-hf-write": false } }, "/domains": { "get": { "operationId": "queryDomains", "tags": [ "Domains" ], "summary": "The account's domains", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "account", "in": "query", "required": false, "description": "the account's username (staff tokens; a customer's token always uses its own account)", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" }, "x-hf-generic": true }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" }, "x-hf-generic": true }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" }, "x-hf-generic": true }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" }, "x-hf-generic": true }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Domain" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ { "domain": "example", "type": "example", "ssl": true, "ssl_expires": "example", "php": "example", "folder": "example", "target": "example" } ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false } }, "/mailboxes": { "get": { "operationId": "queryMailboxes", "tags": [ "Email" ], "summary": "The account's mailboxes", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "account", "in": "query", "required": false, "description": "the account's username (staff tokens; a customer's token always uses its own account)", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" }, "x-hf-generic": true }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" }, "x-hf-generic": true }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" }, "x-hf-generic": true }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" }, "x-hf-generic": true }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "type": "object" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ {} ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false } }, "/databases": { "get": { "operationId": "queryDatabases", "tags": [ "Databases" ], "summary": "The account's MySQL databases", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "account", "in": "query", "required": false, "description": "the account's username (staff tokens; a customer's token always uses its own account)", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" }, "x-hf-generic": true }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" }, "x-hf-generic": true }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" }, "x-hf-generic": true }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" }, "x-hf-generic": true }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "type": "object" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ {} ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false } }, "/mongo": { "get": { "operationId": "getMongo", "tags": [ "MongoDB" ], "summary": "MongoDB databases, users and remote access", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "account", "in": "query", "required": false, "description": "the account's username (staff tokens; a customer's token always uses its own account)", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "post": { "operationId": "createMongoDatabase", "tags": [ "MongoDB" ], "summary": "Create a MongoDB database", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token. Send an Idempotency-Key header to retry safely.", "parameters": [ { "name": "account", "in": "query", "required": false, "description": "the account's username (staff tokens; a customer's token always uses its own account)", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "the name, with or without _" }, "user": { "type": "boolean", "description": "also make a user of the same name (default true)" } }, "required": [ "name" ] }, "example": { "name": "example" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/mongo/{database}": { "delete": { "operationId": "deleteMongoDatabase", "tags": [ "MongoDB" ], "summary": "Drop a MongoDB database", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "database", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "account", "in": "query", "required": false, "description": "the account's username (staff tokens; a customer's token always uses its own account)", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/mongo/{database}/grant": { "post": { "operationId": "grantMongoRole", "tags": [ "MongoDB" ], "summary": "Give a user a role on a database", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "database", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "account", "in": "query", "required": false, "description": "the account's username (staff tokens; a customer's token always uses its own account)", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "string", "description": "the user" }, "role": { "type": "string", "enum": [ "readWrite", "read" ], "description": "default readWrite" } }, "required": [ "user" ] }, "example": { "user": "example" } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/mongo/{database}/revoke": { "post": { "operationId": "revokeMongoRole", "tags": [ "MongoDB" ], "summary": "Take a user's role away", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "database", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "account", "in": "query", "required": false, "description": "the account's username (staff tokens; a customer's token always uses its own account)", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "string", "description": "the user" } }, "required": [ "user" ] }, "example": { "user": "example" } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/mongo/users": { "post": { "operationId": "createMongoUser", "tags": [ "MongoDB" ], "summary": "Create a MongoDB user", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token. Send an Idempotency-Key header to retry safely.", "parameters": [ { "name": "account", "in": "query", "required": false, "description": "the account's username (staff tokens; a customer's token always uses its own account)", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "the name, with or without _" }, "password": { "type": "string", "description": "empty = a random one" } }, "required": [ "name" ] }, "example": { "name": "example" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/mongo/users/{user}/password": { "post": { "operationId": "setMongoUserPassword", "tags": [ "MongoDB" ], "summary": "Set a MongoDB user's password", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "account", "in": "query", "required": false, "description": "the account's username (staff tokens; a customer's token always uses its own account)", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "password": { "type": "string", "description": "empty = a random one" } } }, "example": { "password": "example" } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true }, "put": { "operationId": "setMongoUserPasswordPut", "tags": [ "MongoDB" ], "summary": "Set a MongoDB user's password", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "account", "in": "query", "required": false, "description": "the account's username (staff tokens; a customer's token always uses its own account)", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "password": { "type": "string", "description": "empty = a random one" } } }, "example": { "password": "example" } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/mongo/users/{user}": { "delete": { "operationId": "deleteMongoUser", "tags": [ "MongoDB" ], "summary": "Delete a MongoDB user", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "account", "in": "query", "required": false, "description": "the account's username (staff tokens; a customer's token always uses its own account)", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/mongo/remote": { "post": { "operationId": "setMongoRemoteAccess", "tags": [ "MongoDB" ], "summary": "Set the addresses allowed to connect from outside", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "account", "in": "query", "required": false, "description": "the account's username (staff tokens; a customer's token always uses its own account)", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "ips": { "type": "array", "items": { "type": "string" }, "description": "addresses or ranges (or one text separated by spaces)" } } }, "example": { "ips": [ "example" ] } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true }, "put": { "operationId": "setMongoRemoteAccessPut", "tags": [ "MongoDB" ], "summary": "Set the addresses allowed to connect from outside", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "account", "in": "query", "required": false, "description": "the account's username (staff tokens; a customer's token always uses its own account)", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "ips": { "type": "array", "items": { "type": "string" }, "description": "addresses or ranges (or one text separated by spaces)" } } }, "example": { "ips": [ "example" ] } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/status": { "get": { "operationId": "getStatus", "tags": [ "Server" ], "summary": "The server's load, memory, disk and services", "description": "Any token.", "parameters": [ { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "any", "x-hf-write": false } }, "/sync/sites": { "get": { "operationId": "listSyncSites", "tags": [ "Server" ], "summary": "The websites the token may sync with", "description": "Any token.", "parameters": [ { "name": "account", "in": "query", "required": false, "description": "the account's username (staff tokens; a customer's token always uses its own account)", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "any", "x-hf-write": false } }, "/openapi.json": { "get": { "operationId": "getOpenAPI", "tags": [ "General" ], "summary": "This API as an OpenAPI 3.1 description", "description": "No token needed.", "security": [], "responses": { "200": { "description": "The OpenAPI document", "content": { "application/json": { "schema": { "type": "object" } } } } }, "x-hf-who": "public", "x-hf-write": false } }, "/packages/{package}": { "get": { "operationId": "getPackage", "tags": [ "Packages" ], "summary": "One package (by id or name)", "description": "Administrator and reseller tokens.", "parameters": [ { "name": "package", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/Package" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "name": "example", "disk_mb": 1, "max_domains": 1, "max_databases": 1, "max_mongo_databases": 1, "max_mailboxes": 1, "price_month": 1.5, "redis_mb": 1, "memcached_mb": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "staff", "x-hf-write": false }, "patch": { "operationId": "updatePackage", "tags": [ "Packages" ], "summary": "Change a package (fields left out keep their value)", "description": "Administrator tokens only. Needs a \"Read & change\" token.", "parameters": [ { "name": "package", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "the package's name (up to 40 characters)" }, "disk_mb": { "type": "integer", "description": "disk space in MB (stored in whole GB, rounded); 0 = no limit" }, "max_domains": { "type": "integer", "description": "domains; 0 = no limit" }, "max_databases": { "type": "integer", "description": "MySQL and PostgreSQL databases; 0 = no limit" }, "max_mongo_databases": { "type": "integer", "description": "MongoDB databases (0–1000)" }, "max_mailboxes": { "type": "integer", "description": "email accounts; 0 = no limit" }, "price_month": { "type": "number", "description": "monthly price" }, "cpu": { "type": "number", "description": "CPU cores (0.1 or more; 0 = no limit)" }, "memory_mb": { "type": "integer", "description": "memory in MB (128 or more; 0 = no limit)" }, "max_procs": { "type": "integer", "description": "processes (20 or more; 0 = no limit)" }, "redis_mb": { "type": "integer", "description": "Redis memory in MB (16–8192; 0 = none)" }, "memcached_mb": { "type": "integer", "description": "Memcached memory in MB (16–8192; 0 = none)" }, "mail_hour": { "type": "integer", "description": "emails sent per hour (0 = the server default)" }, "mail_day": { "type": "integer", "description": "emails sent per day (0 = the server default)" }, "max_docker": { "type": "integer", "description": "Docker apps (0–50)" }, "trial_days": { "type": "integer", "description": "free trial days (0–90)" }, "max_files": { "type": "integer", "description": "files (inodes); 0 = no limit" }, "team_members": { "type": "integer", "description": "team members (0 = unlimited, -1 = none, up to 100)" }, "webdisk_users": { "type": "integer", "description": "Web Disk logins (0–1000)" }, "io_mbps": { "type": "integer", "description": "disk speed in MB/s (5 or more; 0 = no limit)" }, "iops": { "type": "integer", "description": "disk operations per second (100 or more; 0 = no limit)" }, "feature_list": { "type": "integer", "description": "the feature list's id (0 = every feature)" }, "php_workers": { "type": "integer", "description": "PHP workers per website (0 = no limit)" }, "app_processes": { "type": "integer", "description": "processes per Node.js, Python or Ruby app (5 or more; 0 = no limit)" } } }, "example": { "name": "example", "disk_mb": 1, "max_domains": 1, "max_databases": 1 } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/Package" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "name": "example", "disk_mb": 1, "max_domains": 1, "max_databases": 1, "max_mongo_databases": 1, "max_mailboxes": 1, "price_month": 1.5, "redis_mb": 1, "memcached_mb": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": true }, "put": { "operationId": "updatePackagePut", "tags": [ "Packages" ], "summary": "Change a package (fields left out keep their value)", "description": "Administrator tokens only. Needs a \"Read & change\" token.", "parameters": [ { "name": "package", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "the package's name (up to 40 characters)" }, "disk_mb": { "type": "integer", "description": "disk space in MB (stored in whole GB, rounded); 0 = no limit" }, "max_domains": { "type": "integer", "description": "domains; 0 = no limit" }, "max_databases": { "type": "integer", "description": "MySQL and PostgreSQL databases; 0 = no limit" }, "max_mongo_databases": { "type": "integer", "description": "MongoDB databases (0–1000)" }, "max_mailboxes": { "type": "integer", "description": "email accounts; 0 = no limit" }, "price_month": { "type": "number", "description": "monthly price" }, "cpu": { "type": "number", "description": "CPU cores (0.1 or more; 0 = no limit)" }, "memory_mb": { "type": "integer", "description": "memory in MB (128 or more; 0 = no limit)" }, "max_procs": { "type": "integer", "description": "processes (20 or more; 0 = no limit)" }, "redis_mb": { "type": "integer", "description": "Redis memory in MB (16–8192; 0 = none)" }, "memcached_mb": { "type": "integer", "description": "Memcached memory in MB (16–8192; 0 = none)" }, "mail_hour": { "type": "integer", "description": "emails sent per hour (0 = the server default)" }, "mail_day": { "type": "integer", "description": "emails sent per day (0 = the server default)" }, "max_docker": { "type": "integer", "description": "Docker apps (0–50)" }, "trial_days": { "type": "integer", "description": "free trial days (0–90)" }, "max_files": { "type": "integer", "description": "files (inodes); 0 = no limit" }, "team_members": { "type": "integer", "description": "team members (0 = unlimited, -1 = none, up to 100)" }, "webdisk_users": { "type": "integer", "description": "Web Disk logins (0–1000)" }, "io_mbps": { "type": "integer", "description": "disk speed in MB/s (5 or more; 0 = no limit)" }, "iops": { "type": "integer", "description": "disk operations per second (100 or more; 0 = no limit)" }, "feature_list": { "type": "integer", "description": "the feature list's id (0 = every feature)" }, "php_workers": { "type": "integer", "description": "PHP workers per website (0 = no limit)" }, "app_processes": { "type": "integer", "description": "processes per Node.js, Python or Ruby app (5 or more; 0 = no limit)" } } }, "example": { "name": "example", "disk_mb": 1, "max_domains": 1, "max_databases": 1 } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/Package" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "name": "example", "disk_mb": 1, "max_domains": 1, "max_databases": 1, "max_mongo_databases": 1, "max_mailboxes": 1, "price_month": 1.5, "redis_mb": 1, "memcached_mb": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": true }, "delete": { "operationId": "deletePackage", "tags": [ "Packages" ], "summary": "Delete a package no account uses", "description": "Administrator tokens only. Needs a \"Read & change\" token.", "parameters": [ { "name": "package", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": true } }, "/resellers": { "get": { "operationId": "listResellers", "tags": [ "Resellers" ], "summary": "Every reseller", "description": "Administrator tokens only.", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" }, "x-hf-generic": true }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" }, "x-hf-generic": true }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" }, "x-hf-generic": true }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" }, "x-hf-generic": true }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Reseller" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ { "username": "example", "email": "example", "status": "example", "max_accounts": 1, "accounts": 1, "approval": "example", "created_at": "example" } ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": false }, "post": { "operationId": "createReseller", "tags": [ "Resellers" ], "summary": "Create a reseller", "description": "Administrator tokens only. Needs a \"Read & change\" token. Send an Idempotency-Key header to retry safely.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "username": { "type": "string", "description": "3–16 lower-case letters and numbers, starting with a letter" }, "email": { "type": "string", "description": "contact email" }, "password": { "type": "string", "description": "empty = a random one, returned once" }, "max_accounts": { "type": "integer", "description": "accounts they may make; 0 = no limit" }, "welcome": { "type": "boolean", "description": "email the welcome message" } }, "required": [ "username", "email" ] }, "example": { "username": "example", "email": "example" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": true } }, "/resellers/{username}": { "get": { "operationId": "getReseller", "tags": [ "Resellers" ], "summary": "One reseller", "description": "Administrator tokens only.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/Reseller" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "username": "example", "email": "example", "status": "example", "max_accounts": 1, "accounts": 1, "approval": "example", "created_at": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": false }, "delete": { "operationId": "deleteReseller", "tags": [ "Resellers" ], "summary": "Delete a reseller (their customers move to the administrator)", "description": "Administrator tokens only. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": true } }, "/resellers/{username}/suspend": { "post": { "operationId": "suspendReseller", "tags": [ "Resellers" ], "summary": "Suspend a reseller's login (their customers keep working)", "description": "Administrator tokens only. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/Reseller" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "username": "example", "email": "example", "status": "example", "max_accounts": 1, "accounts": 1, "approval": "example", "created_at": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": true } }, "/resellers/{username}/unsuspend": { "post": { "operationId": "unsuspendReseller", "tags": [ "Resellers" ], "summary": "Reactivate a reseller", "description": "Administrator tokens only. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/Reseller" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "username": "example", "email": "example", "status": "example", "max_accounts": 1, "accounts": 1, "approval": "example", "created_at": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": true } }, "/resellers/{username}/limit": { "post": { "operationId": "setResellerLimit", "tags": [ "Resellers" ], "summary": "Set a reseller's account limit", "description": "Administrator tokens only. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "max_accounts": { "type": "integer", "description": "0 = no limit" } }, "required": [ "max_accounts" ] }, "example": { "max_accounts": 1 } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/Reseller" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "username": "example", "email": "example", "status": "example", "max_accounts": 1, "accounts": 1, "approval": "example", "created_at": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": true }, "put": { "operationId": "setResellerLimitPut", "tags": [ "Resellers" ], "summary": "Set a reseller's account limit", "description": "Administrator tokens only. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "max_accounts": { "type": "integer", "description": "0 = no limit" } }, "required": [ "max_accounts" ] }, "example": { "max_accounts": 1 } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/Reseller" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "username": "example", "email": "example", "status": "example", "max_accounts": 1, "accounts": 1, "approval": "example", "created_at": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": true } }, "/accounts/{username}/domains": { "get": { "operationId": "listDomains", "tags": [ "Domains" ], "summary": "The account's domains", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" }, "x-hf-generic": true }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" }, "x-hf-generic": true }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" }, "x-hf-generic": true }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" }, "x-hf-generic": true }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Domain" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ { "domain": "example", "type": "example", "ssl": true, "ssl_expires": "example", "php": "example", "folder": "example", "target": "example" } ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "post": { "operationId": "addDomain", "tags": [ "Domains" ], "summary": "Add a website, subdomain or parked domain", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token. Send an Idempotency-Key header to retry safely.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "description": "the domain (a subdomain in full, or only its first part with parent)" }, "type": { "type": "string", "enum": [ "addon", "sub", "parked" ], "description": "default addon" }, "folder": { "type": "string", "description": "the document folder inside web/ (addon and sub)" }, "parent": { "type": "string", "description": "sub: the main domain it belongs to" }, "target": { "type": "string", "description": "parked: the website it shows" } }, "required": [ "domain" ] }, "example": { "domain": "example" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/Domain" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "domain": "example", "type": "example", "ssl": true, "ssl_expires": "example", "php": "example", "folder": "example", "target": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/domains/{domain}": { "patch": { "operationId": "updateDomain", "tags": [ "Domains" ], "summary": "Set a website's document folder or PHP version", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "folder": { "type": "string", "description": "the document folder inside web/" }, "php": { "type": "string", "description": "an installed PHP version, e.g. 8.3" } } }, "example": { "folder": "example", "php": "example" } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/Domain" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "domain": "example", "type": "example", "ssl": true, "ssl_expires": "example", "php": "example", "folder": "example", "target": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true }, "put": { "operationId": "updateDomainPut", "tags": [ "Domains" ], "summary": "Set a website's document folder or PHP version", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "folder": { "type": "string", "description": "the document folder inside web/" }, "php": { "type": "string", "description": "an installed PHP version, e.g. 8.3" } } }, "example": { "folder": "example", "php": "example" } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/Domain" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "domain": "example", "type": "example", "ssl": true, "ssl_expires": "example", "php": "example", "folder": "example", "target": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true }, "delete": { "operationId": "removeDomain", "tags": [ "Domains" ], "summary": "Remove a domain", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "purge", "in": "query", "required": false, "description": "1 = delete its files too", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/domains/{domain}/speed": { "get": { "operationId": "getSiteSpeed", "tags": [ "Domains" ], "summary": "A website's speed settings (page cache, compression, browser cache)", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "patch": { "operationId": "setSiteSpeed", "tags": [ "Domains" ], "summary": "Change a website's speed settings", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "page_cache": { "type": "integer", "description": "minutes the page cache keeps pages: 0 (off), 5, 10, 30 or 60" }, "cache_query_strings": { "type": "string", "enum": [ "on", "off", "default" ], "description": "also cache addresses with a query string" }, "compression": { "type": "string", "enum": [ "on", "off", "default" ], "description": "gzip/brotli compression of text files" }, "browser_cache_days": { "type": "string", "enum": [ "0", "1", "7", "30", "365", "default" ], "description": "days browsers keep images, styles and scripts" } } }, "example": { "page_cache": 1, "cache_query_strings": "on", "compression": "on", "browser_cache_days": "0" } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true }, "put": { "operationId": "setSiteSpeedPut", "tags": [ "Domains" ], "summary": "Change a website's speed settings", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "page_cache": { "type": "integer", "description": "minutes the page cache keeps pages: 0 (off), 5, 10, 30 or 60" }, "cache_query_strings": { "type": "string", "enum": [ "on", "off", "default" ], "description": "also cache addresses with a query string" }, "compression": { "type": "string", "enum": [ "on", "off", "default" ], "description": "gzip/brotli compression of text files" }, "browser_cache_days": { "type": "string", "enum": [ "0", "1", "7", "30", "365", "default" ], "description": "days browsers keep images, styles and scripts" } } }, "example": { "page_cache": 1, "cache_query_strings": "on", "compression": "on", "browser_cache_days": "0" } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/domains/{domain}/cache/purge": { "post": { "operationId": "purgeSiteCache", "tags": [ "Domains" ], "summary": "Empty a website's page cache", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/domains/{domain}/speed-test": { "post": { "operationId": "runSpeedTest", "tags": [ "Domains" ], "summary": "Run a speed test of a website now (at most 20 an hour per account)", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true }, "get": { "operationId": "getSpeedTest", "tags": [ "Domains" ], "summary": "A website's latest speed test (null before the first)", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false } }, "/accounts/{username}/domains/{domain}/site-check": { "get": { "operationId": "getSiteCheck", "tags": [ "Domains" ], "summary": "A website's site check: schedule, the newest run with its problems, and the run history", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "post": { "operationId": "runSiteCheck", "tags": [ "Domains" ], "summary": "Check a website now (starts within a minute; not again within 10 minutes)", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true }, "patch": { "operationId": "setSiteCheck", "tags": [ "Domains" ], "summary": "Set a website's site check schedule and summary emails", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "frequency": { "type": "string", "enum": [ "daily", "weekly", "off" ], "description": "how often the website is checked" }, "emails": { "type": "boolean", "description": "email a weekly summary when the problems change" } } }, "example": { "frequency": "daily", "emails": true } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true }, "put": { "operationId": "setSiteCheckPut", "tags": [ "Domains" ], "summary": "Set a website's site check schedule and summary emails", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "frequency": { "type": "string", "enum": [ "daily", "weekly", "off" ], "description": "how often the website is checked" }, "emails": { "type": "boolean", "description": "email a weekly summary when the problems change" } } }, "example": { "frequency": "daily", "emails": true } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/email/imports": { "get": { "operationId": "listMailImports", "tags": [ "Email" ], "summary": "Mail imports from another provider (the last 30 days)", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" }, "x-hf-generic": true }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" }, "x-hf-generic": true }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" }, "x-hf-generic": true }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" }, "x-hf-generic": true }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/MailImport" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ { "id": 1, "mailbox": "example", "source": "example", "status": "example", "folders": 1, "folders_done": 1, "messages": 1, "copied": 1, "skipped": 1, "errors": 1, "current_folder": "example", "created_at": "example", "result": "example" } ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "post": { "operationId": "startMailImport", "tags": [ "Email" ], "summary": "Copy a mailbox from another provider over IMAP, in the background", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token. Send an Idempotency-Key header to retry safely.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mailbox": { "type": "string", "description": "the address here to copy into" }, "host": { "type": "string", "description": "the old IMAP server (a public name or address)" }, "security": { "type": "string", "enum": [ "ssl", "starttls" ], "description": "ssl (default port 993) or starttls (143)" }, "port": { "type": "integer", "description": "the old server's port" }, "login": { "type": "string", "description": "the login there" }, "password": { "type": "string", "description": "the password there; kept sealed until the import ends" }, "folders": { "type": "array", "items": { "type": "string" }, "description": "the folders to copy (empty = all)" }, "skip_duplicates": { "type": "boolean", "description": "skip messages already in the mailbox (default true)" } }, "required": [ "mailbox", "host", "login", "password" ] }, "example": { "mailbox": "example", "host": "example", "login": "example", "password": "example" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/MailImport" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "mailbox": "example", "source": "example", "status": "example", "folders": 1, "folders_done": 1, "messages": 1, "copied": 1, "skipped": 1, "errors": 1, "current_folder": "example", "created_at": "example", "result": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/email/imports/{id}": { "get": { "operationId": "getMailImport", "tags": [ "Email" ], "summary": "One mail import, with its log", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/MailImport" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "mailbox": "example", "source": "example", "status": "example", "folders": 1, "folders_done": 1, "messages": 1, "copied": 1, "skipped": 1, "errors": 1, "current_folder": "example", "created_at": "example", "result": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "delete": { "operationId": "cancelMailImport", "tags": [ "Email" ], "summary": "Cancel a mail import", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/MailImport" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "mailbox": "example", "source": "example", "status": "example", "folders": 1, "folders_done": 1, "messages": 1, "copied": 1, "skipped": 1, "errors": 1, "current_folder": "example", "created_at": "example", "result": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/email/limits": { "get": { "operationId": "getMailLimits", "tags": [ "Email" ], "summary": "Sending limits (emails per hour and per day), what was sent and recent limit events", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "put": { "operationId": "setMailLimits", "tags": [ "Email" ], "summary": "Set the account's own sending limits (null = the package's)", "description": "Administrator tokens only. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "per_hour": { "type": "integer", "description": "emails per hour; 0 = unlimited, null or -1 = the package's" }, "per_day": { "type": "integer", "description": "emails per day; 0 = unlimited, null or -1 = the package's" } } }, "example": { "per_hour": 1, "per_day": 1 } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": true }, "patch": { "operationId": "setMailLimitsPatch", "tags": [ "Email" ], "summary": "Set the account's own sending limits (null = the package's)", "description": "Administrator tokens only. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "per_hour": { "type": "integer", "description": "emails per hour; 0 = unlimited, null or -1 = the package's" }, "per_day": { "type": "integer", "description": "emails per day; 0 = unlimited, null or -1 = the package's" } } }, "example": { "per_hour": 1, "per_day": 1 } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": true } }, "/accounts/{username}/email/limits/release": { "post": { "operationId": "releaseMailLimits", "tags": [ "Email" ], "summary": "Let the account send again after a reached limit or a hold", "description": "Administrator tokens only. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": true } }, "/accounts/{username}/email/checks/{domain}": { "get": { "operationId": "getMailChecks", "tags": [ "Email" ], "summary": "Email checks of a mail domain: MX, SPF, DKIM, DMARC, reverse DNS, TLS and blocklists, with the fixes", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false } }, "/accounts/{username}/email/checks/{domain}/fix": { "post": { "operationId": "fixMailCheck", "tags": [ "Email" ], "summary": "Fix a failed check in the domain's DNS zone (when this server runs it)", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "check": { "type": "string", "enum": [ "mx", "spf", "dkim", "dmarc" ], "description": "the check to fix" }, "report_to": { "type": "string", "description": "DMARC: the address that gets the reports (default: the account's email)" } }, "required": [ "check" ] }, "example": { "check": "mx" } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/mysql": { "get": { "operationId": "getMysql", "tags": [ "Databases" ], "summary": "MySQL: the host, the account's limit and how many databases it has", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false } }, "/accounts/{username}/postgres": { "get": { "operationId": "getPostgres", "tags": [ "Databases" ], "summary": "PostgreSQL: the host and port, the account's limit and how many databases it has", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false } }, "/ssl/autossl": { "post": { "operationId": "runAutoSSL", "tags": [ "SSL" ], "summary": "Run AutoSSL now for every due domain", "description": "Administrator tokens only. Needs a \"Read & change\" token.", "parameters": [ { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": true } }, "/accounts/{username}/backup-targets": { "get": { "operationId": "listBackupTargets", "tags": [ "Backups" ], "summary": "The account's own backup storage places (S3-compatible or SFTP; no secrets)", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" }, "x-hf-generic": true }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" }, "x-hf-generic": true }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" }, "x-hf-generic": true }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" }, "x-hf-generic": true }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/BackupTarget" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ { "id": 1, "name": "example", "kind": "example", "summary": "example", "path": "example", "freq": "example", "weekday": 1, "hour": 1, "keep_days": 1, "next_run": 1, "last": {}, "test": {} } ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "post": { "operationId": "createBackupTarget", "tags": [ "Backups" ], "summary": "Add own backup storage (its connection is tested)", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token. Send an Idempotency-Key header to retry safely.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "s3", "sftp" ], "description": "s3 or sftp (can't be changed later)" }, "name": { "type": "string", "description": "a name (up to 40 characters)" }, "path": { "type": "string", "description": "the folder on the storage" }, "s3_endpoint": { "type": "string", "description": "s3: https://host[:port]" }, "s3_region": { "type": "string", "description": "s3: the region" }, "s3_bucket": { "type": "string", "description": "s3: the bucket" }, "s3_access_key": { "type": "string", "description": "s3: the access key" }, "s3_secret_key": { "type": "string", "description": "s3: the secret key (kept sealed, never answered)" }, "sftp_host": { "type": "string", "description": "sftp: the server (its host key is pinned the first time)" }, "sftp_port": { "type": "integer", "description": "sftp: the port (default 22)" }, "sftp_user": { "type": "string", "description": "sftp: the user" }, "sftp_password": { "type": "string", "description": "sftp: the password (or sftp_key)" }, "sftp_key": { "type": "string", "description": "sftp: a private key" }, "freq": { "type": "string", "enum": [ "off", "daily", "weekly" ], "description": "how often a fresh backup is copied" }, "weekday": { "type": "integer", "description": "weekly: 0 = Sunday … 6" }, "hour": { "type": "integer", "description": "the hour (0–23, UTC)" }, "keep_days": { "type": "integer", "description": "days copies are kept there (1–3650)" } }, "required": [ "kind", "name" ] }, "example": { "kind": "s3", "name": "example" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/BackupTarget" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "name": "example", "kind": "example", "summary": "example", "path": "example", "freq": "example", "weekday": 1, "hour": 1, "keep_days": 1, "next_run": 1, "last": {}, "test": {} } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/backup-targets/{id}": { "get": { "operationId": "getBackupTarget", "tags": [ "Backups" ], "summary": "One own backup storage place", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/BackupTarget" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "name": "example", "kind": "example", "summary": "example", "path": "example", "freq": "example", "weekday": 1, "hour": 1, "keep_days": 1, "next_run": 1, "last": {}, "test": {} } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "patch": { "operationId": "updateBackupTarget", "tags": [ "Backups" ], "summary": "Change own backup storage (a secret left out stays as it is)", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "s3", "sftp" ], "description": "s3 or sftp (can't be changed later)" }, "name": { "type": "string", "description": "a name (up to 40 characters)" }, "path": { "type": "string", "description": "the folder on the storage" }, "s3_endpoint": { "type": "string", "description": "s3: https://host[:port]" }, "s3_region": { "type": "string", "description": "s3: the region" }, "s3_bucket": { "type": "string", "description": "s3: the bucket" }, "s3_access_key": { "type": "string", "description": "s3: the access key" }, "s3_secret_key": { "type": "string", "description": "s3: the secret key (kept sealed, never answered)" }, "sftp_host": { "type": "string", "description": "sftp: the server (its host key is pinned the first time)" }, "sftp_port": { "type": "integer", "description": "sftp: the port (default 22)" }, "sftp_user": { "type": "string", "description": "sftp: the user" }, "sftp_password": { "type": "string", "description": "sftp: the password (or sftp_key)" }, "sftp_key": { "type": "string", "description": "sftp: a private key" }, "freq": { "type": "string", "enum": [ "off", "daily", "weekly" ], "description": "how often a fresh backup is copied" }, "weekday": { "type": "integer", "description": "weekly: 0 = Sunday … 6" }, "hour": { "type": "integer", "description": "the hour (0–23, UTC)" }, "keep_days": { "type": "integer", "description": "days copies are kept there (1–3650)" } } }, "example": { "kind": "s3", "name": "example", "path": "example", "s3_endpoint": "example" } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/BackupTarget" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "name": "example", "kind": "example", "summary": "example", "path": "example", "freq": "example", "weekday": 1, "hour": 1, "keep_days": 1, "next_run": 1, "last": {}, "test": {} } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true }, "put": { "operationId": "updateBackupTargetPut", "tags": [ "Backups" ], "summary": "Change own backup storage (a secret left out stays as it is)", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "s3", "sftp" ], "description": "s3 or sftp (can't be changed later)" }, "name": { "type": "string", "description": "a name (up to 40 characters)" }, "path": { "type": "string", "description": "the folder on the storage" }, "s3_endpoint": { "type": "string", "description": "s3: https://host[:port]" }, "s3_region": { "type": "string", "description": "s3: the region" }, "s3_bucket": { "type": "string", "description": "s3: the bucket" }, "s3_access_key": { "type": "string", "description": "s3: the access key" }, "s3_secret_key": { "type": "string", "description": "s3: the secret key (kept sealed, never answered)" }, "sftp_host": { "type": "string", "description": "sftp: the server (its host key is pinned the first time)" }, "sftp_port": { "type": "integer", "description": "sftp: the port (default 22)" }, "sftp_user": { "type": "string", "description": "sftp: the user" }, "sftp_password": { "type": "string", "description": "sftp: the password (or sftp_key)" }, "sftp_key": { "type": "string", "description": "sftp: a private key" }, "freq": { "type": "string", "enum": [ "off", "daily", "weekly" ], "description": "how often a fresh backup is copied" }, "weekday": { "type": "integer", "description": "weekly: 0 = Sunday … 6" }, "hour": { "type": "integer", "description": "the hour (0–23, UTC)" }, "keep_days": { "type": "integer", "description": "days copies are kept there (1–3650)" } } }, "example": { "kind": "s3", "name": "example", "path": "example", "s3_endpoint": "example" } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/BackupTarget" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "name": "example", "kind": "example", "summary": "example", "path": "example", "freq": "example", "weekday": 1, "hour": 1, "keep_days": 1, "next_run": 1, "last": {}, "test": {} } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true }, "delete": { "operationId": "deleteBackupTarget", "tags": [ "Backups" ], "summary": "Remove own backup storage (the copies there stay)", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/backup-targets/{id}/test": { "post": { "operationId": "testBackupTarget", "tags": [ "Backups" ], "summary": "Test the connection (a small file is written, read back and deleted)", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/backup-targets/{id}/run": { "post": { "operationId": "runBackupTarget", "tags": [ "Backups" ], "summary": "Copy a backup there now: a fresh one, or one on the server", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "backup": { "type": "string", "description": "a backup on the server to copy (empty = make a fresh one, copied and then removed from the server)" } } }, "example": { "backup": "example" } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/backup-targets/{id}/copies": { "get": { "operationId": "listBackupTargetCopies", "tags": [ "Backups" ], "summary": "The account's backups on that storage, newest first", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" }, "x-hf-generic": true }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" }, "x-hf-generic": true }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" }, "x-hf-generic": true }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" }, "x-hf-generic": true }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Backup" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ { "name": "example", "size": 1, "created_at": "example" } ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false } }, "/accounts/{username}/backup-targets/{id}/restore": { "post": { "operationId": "restoreFromBackupTarget", "tags": [ "Backups" ], "summary": "Restore all or one part of a copy on that storage", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "backup": { "type": "string", "description": "the copy's name" }, "what": { "type": "string", "enum": [ "all", "files", "databases", "mail", "cron" ], "description": "what to restore" } }, "required": [ "backup", "what" ] }, "example": { "backup": "example", "what": "all" } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/ssh/import": { "post": { "operationId": "importSSHKeys", "tags": [ "SSH keys" ], "summary": "Add several public keys at once (one per line, as in authorized_keys)", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "keys": { "type": "string", "description": "the key lines" }, "name": { "type": "string", "description": "the name of keys without a comment" } }, "required": [ "keys" ] }, "example": { "keys": "example" } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/ssh/generate": { "post": { "operationId": "generateSSHKey", "tags": [ "SSH keys" ], "summary": "Make a key pair on the server as the account; the private key is answered once and not kept", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token. Send an Idempotency-Key header to retry safely.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ed25519", "rsa", "ecdsa" ], "description": "the key type (default ed25519)" }, "comment": { "type": "string", "description": "the key's comment" }, "add": { "type": "boolean", "description": "add the public key to the account's keys (default true)" } } }, "example": { "type": "ed25519", "comment": "example", "add": true } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/ssh/access": { "get": { "operationId": "getSSHAccess", "tags": [ "SSH keys" ], "summary": "Whether SSH and SFTP logins are on, and whether the plan lets the customer switch them", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "post": { "operationId": "setSSHAccess", "tags": [ "SSH keys" ], "summary": "Switch SSH and SFTP logins on or off (when the plan allows it)", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "on or off" } }, "required": [ "enabled" ] }, "example": { "enabled": true } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/apps": { "get": { "operationId": "listApps", "tags": [ "Apps" ], "summary": "The apps the account can install, with their version and requirements", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" }, "x-hf-generic": true }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" }, "x-hf-generic": true }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" }, "x-hf-generic": true }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" }, "x-hf-generic": true }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "type": "object" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ {} ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false } }, "/accounts/{username}/apps/installs": { "get": { "operationId": "listAppInstalls", "tags": [ "Apps" ], "summary": "The apps installed on the account's websites, with their version and update state", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" }, "x-hf-generic": true }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" }, "x-hf-generic": true }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" }, "x-hf-generic": true }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" }, "x-hf-generic": true }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "type": "object" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ {} ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false } }, "/accounts/{username}/staging": { "get": { "operationId": "listStaging", "tags": [ "Staging" ], "summary": "The account's staging copies", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" }, "x-hf-generic": true }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" }, "x-hf-generic": true }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" }, "x-hf-generic": true }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" }, "x-hf-generic": true }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "type": "object" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ {} ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "post": { "operationId": "createStaging", "tags": [ "Staging" ], "summary": "Copy a website's files and database to a staging copy", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token. Send an Idempotency-Key header to retry safely.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "description": "the live website" }, "name": { "type": "string", "description": "the staging name's first label (empty = staging.)" }, "replace_urls": { "type": "boolean", "description": "replace the address in the database of an app that isn't WordPress (WordPress is always rewritten)" }, "protect": { "type": "boolean", "description": "password-protect it (default true; the password is returned once)" }, "noindex": { "type": "boolean", "description": "tell search engines to stay away (default true)" } }, "required": [ "domain" ] }, "example": { "domain": "example" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/staging/{id}/push": { "post": { "operationId": "pushStaging", "tags": [ "Staging" ], "summary": "Push a staging copy to the live site (a full backup is made first)", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "what": { "type": "string", "enum": [ "files", "db", "both" ], "description": "what to push" } }, "required": [ "what" ] }, "example": { "what": "files" } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/staging/{id}/pull": { "post": { "operationId": "pullStaging", "tags": [ "Staging" ], "summary": "Copy the live site over the staging copy again", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/staging/{id}": { "delete": { "operationId": "deleteStaging", "tags": [ "Staging" ], "summary": "Delete a staging copy, its files and its database", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/clone": { "post": { "operationId": "cloneSite", "tags": [ "Site templates" ], "summary": "Copy a website (files and database, not mail) to a new address, over another website, or (staff) into another account", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token. Send an Idempotency-Key header to retry safely.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "description": "the website to copy" }, "name": { "type": "string", "description": "the new address (a subdomain or another domain)" }, "to": { "type": "string", "description": "an existing website of the account to copy over (instead of name)" }, "confirm": { "type": "boolean", "description": "with to: confirm its files are replaced" }, "to_account": { "type": "string", "description": "staff tokens: the username of another account they manage to copy into" }, "database": { "type": "string", "description": "one of the account's databases to copy when the site's config names none" }, "replace_urls": { "type": "boolean", "description": "replace the address in the database of an app that isn't WordPress (WordPress is always rewritten)" }, "ssl": { "type": "boolean", "description": "try a free certificate for the copy at once (default true)" } }, "required": [ "domain" ] }, "example": { "domain": "example" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/templates": { "get": { "operationId": "listSiteTemplates", "tags": [ "Site templates" ], "summary": "The account's own site templates and the shared ones offered to it", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" }, "x-hf-generic": true }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" }, "x-hf-generic": true }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" }, "x-hf-generic": true }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" }, "x-hf-generic": true }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "type": "object" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ {} ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "post": { "operationId": "createSiteTemplate", "tags": [ "Site templates" ], "summary": "Save a website as a template (files and database; the package's template size limit applies)", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token. Send an Idempotency-Key header to retry safely.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "description": "the website to save" }, "title": { "type": "string", "description": "the template's name" }, "uploads": { "type": "boolean", "description": "keep the uploads folders (default true)" }, "shared": { "type": "boolean", "description": "staff tokens: save it as a shared template offered to their customers" } }, "required": [ "domain", "title" ] }, "example": { "domain": "example", "title": "example" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/templates/{id}": { "delete": { "operationId": "deleteSiteTemplate", "tags": [ "Site templates" ], "summary": "Delete a site template (websites made from it stay)", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/templates/{id}/site": { "post": { "operationId": "createSiteFromTemplate", "tags": [ "Site templates" ], "summary": "Make a new website from a template, with its placeholders filled in", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token. Send an Idempotency-Key header to retry safely.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "the new address" }, "title": { "type": "string", "description": "the site title ({{site_title}}; WordPress: blogname)" }, "admin_email": { "type": "string", "description": "the admin email ({{admin_email}}; default: the account's email)" } }, "required": [ "name" ] }, "example": { "name": "example" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/wordpress": { "get": { "operationId": "listWordPressSites", "tags": [ "WordPress" ], "summary": "The account's WordPress sites with their updates, security problems and last safe update", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" }, "x-hf-generic": true }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" }, "x-hf-generic": true }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" }, "x-hf-generic": true }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" }, "x-hf-generic": true }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WordPressSite" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ { "id": 1, "folder": "example", "url": "example", "version": "example", "updates": 1, "core_update": "example", "vulnerabilities": 1, "vulnerable": [], "mode": "example", "schedule": "example", "last_status": "example", "last_run_at": "example", "next_run_at": "example", "running": true } ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false } }, "/accounts/{username}/wordpress/{site}/update": { "post": { "operationId": "updateWordPressSite", "tags": [ "WordPress" ], "summary": "Start a safe update of one site (backup first, rolled back when a check fails)", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "site", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "string" }, "description": "only these items, e.g. plugin:woocommerce or core:wordpress (default: everything the site's policy covers)" } } }, "example": { "items": [ "example" ] } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/WordPressRun" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "site": 1, "queued": true, "items": [] } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/db-tools/dumps": { "get": { "operationId": "listDatabaseDumps", "tags": [ "Databases" ], "summary": "The account's database dumps and dump schedules", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "post": { "operationId": "createDatabaseDump", "tags": [ "Databases" ], "summary": "Make a compressed, consistent dump of a database now", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token. Send an Idempotency-Key header to retry safely.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "database": { "type": "string", "description": "the MySQL or PostgreSQL database, e.g. sarah_shop" }, "engine": { "type": "string", "enum": [ "mysql", "postgresql" ], "description": "only needed when a MySQL and a PostgreSQL database share the name" } }, "required": [ "database" ] }, "example": { "database": "example" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/db-tools/dumps/{name}/restore": { "post": { "operationId": "restoreDatabaseDump", "tags": [ "Databases" ], "summary": "Load a dump into its own database or another database of the same engine", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "database": { "type": "string", "description": "the database to load it into (default: the dump's own database)" } } }, "example": { "database": "example" } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/db-tools/slow-queries": { "get": { "operationId": "listSlowQueries", "tags": [ "Databases" ], "summary": "The slowest queries of the account's databases (normalised, with counts and times)", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "database", "in": "query", "required": false, "description": "only this database", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" }, "x-hf-generic": true }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" }, "x-hf-generic": true }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" }, "x-hf-generic": true }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" }, "x-hf-generic": true }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "type": "object" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ {} ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false } }, "/server/services": { "get": { "operationId": "listServices", "tags": [ "Server" ], "summary": "Every service and its state", "description": "Administrator tokens only.", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" }, "x-hf-generic": true }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" }, "x-hf-generic": true }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" }, "x-hf-generic": true }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" }, "x-hf-generic": true }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Service" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ { "name": "example", "state": "example", "running": true } ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": false } }, "/server/services/{service}/restart": { "post": { "operationId": "restartService", "tags": [ "Server" ], "summary": "Restart a service", "description": "Administrator tokens only. Needs a \"Read & change\" token.", "parameters": [ { "name": "service", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/Service" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "name": "example", "state": "example", "running": true } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": true } }, "/server/health": { "get": { "operationId": "getHealth", "tags": [ "Server" ], "summary": "Every health check, worst first", "description": "Administrator tokens only.", "parameters": [ { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": false } }, "/server/version": { "get": { "operationId": "getVersion", "tags": [ "Server" ], "summary": "The installed and newest version", "description": "Administrator tokens only.", "parameters": [ { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/Version" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "version": "example", "latest": "example", "published": "example", "newer": true, "update_running": true, "auto_update": true, "checked_at": "example", "error": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": false } }, "/server/version/check": { "post": { "operationId": "checkForUpdate", "tags": [ "Server" ], "summary": "Look for a new version now", "description": "Administrator tokens only. Needs a \"Read & change\" token.", "parameters": [ { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/Version" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "version": "example", "latest": "example", "published": "example", "newer": true, "update_running": true, "auto_update": true, "checked_at": "example", "error": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": true } }, "/server/moves/suggestions": { "get": { "operationId": "listMoveSuggestions", "tags": [ "Server" ], "summary": "Suggested, planned and running automatic moves", "description": "Administrator tokens only.", "parameters": [ { "name": "history", "in": "query", "required": false, "description": "1 = the last 50 finished, skipped and failed ones instead", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" }, "x-hf-generic": true }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" }, "x-hf-generic": true }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" }, "x-hf-generic": true }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" }, "x-hf-generic": true }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "type": "object" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ {} ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": false } }, "/server/moves/check": { "post": { "operationId": "checkMoves", "tags": [ "Server" ], "summary": "Read every server now and suggest moves", "description": "Administrator tokens only. Needs a \"Read & change\" token.", "parameters": [ { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": true } }, "/server/moves/suggestions/{id}/approve": { "post": { "operationId": "approveMoveSuggestion", "tags": [ "Server" ], "summary": "Approve a suggested move (it runs in the next maintenance window)", "description": "Administrator tokens only. Needs a \"Read & change\" token.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": true } }, "/server/moves/suggestions/{id}/skip": { "post": { "operationId": "skipMoveSuggestion", "tags": [ "Server" ], "summary": "Skip a suggested or planned move", "description": "Administrator tokens only. Needs a \"Read & change\" token.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": true } }, "/status/page": { "get": { "operationId": "getStatusPage", "tags": [ "Status page" ], "summary": "The public status page: each part, open incidents and planned maintenance", "description": "No token needed.", "security": [], "responses": { "200": { "description": "Done", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } } }, "x-hf-who": "public", "x-hf-write": false } }, "/status/incidents": { "get": { "operationId": "listIncidents", "tags": [ "Status page" ], "summary": "Incidents and maintenance, newest first, with their updates", "description": "Administrator tokens only.", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" }, "x-hf-generic": true }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" }, "x-hf-generic": true }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" }, "x-hf-generic": true }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" }, "x-hf-generic": true }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "type": "object" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ {} ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": false }, "post": { "operationId": "createIncident", "tags": [ "Status page" ], "summary": "Post an incident or plan maintenance", "description": "Administrator tokens only. Needs a \"Read & change\" token. Send an Idempotency-Key header to retry safely.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "incident", "maintenance" ], "description": "incident (default) or maintenance" }, "title": { "type": "string", "description": "1–150 characters" }, "body": { "type": "string", "description": "what is happening (up to 5,000 characters)" }, "parts": { "type": "array", "items": { "type": "string" }, "description": "what is affected: web, mail, dns, db, panel" }, "impact": { "type": "string", "enum": [ "minor", "major" ], "description": "incidents: minor (default) or major" }, "starts": { "type": "string", "description": "maintenance: the start, UTC (YYYY-MM-DD HH:MM)" }, "ends": { "type": "string", "description": "maintenance: the end, UTC" }, "email": { "type": "boolean", "description": "also email every customer" } }, "required": [ "title", "body", "parts" ] }, "example": { "title": "example", "body": "example", "parts": [ "example" ] } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": true } }, "/status/incidents/{id}/updates": { "post": { "operationId": "postIncidentUpdate", "tags": [ "Status page" ], "summary": "Post an update (a new step) to an incident or maintenance", "description": "Administrator tokens only. Needs a \"Read & change\" token. Send an Idempotency-Key header to retry safely.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "investigating, identified, monitoring, resolved (incidents); scheduled, in_progress, completed (maintenance)" }, "body": { "type": "string", "description": "the update's text (empty = the step's name)" }, "email": { "type": "boolean", "description": "also email every customer" } }, "required": [ "status" ] }, "example": { "status": "example" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": true } }, "/coupons": { "get": { "operationId": "listCoupons", "tags": [ "Billing" ], "summary": "Every discount code with its rules and uses", "description": "Administrator tokens only.", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" }, "x-hf-generic": true }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" }, "x-hf-generic": true }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" }, "x-hf-generic": true }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" }, "x-hf-generic": true }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "type": "object" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ {} ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": false }, "post": { "operationId": "createCoupon", "tags": [ "Billing" ], "summary": "Make a discount code", "description": "Administrator tokens only. Needs a \"Read & change\" token. Send an Idempotency-Key header to retry safely.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "3–30 letters, numbers, - or _" }, "kind": { "type": "string", "enum": [ "percent", "amount", "trial" ], "description": "percent off, amount off or free months" }, "value": { "type": "number", "description": "the percent, the amount, or the free months" }, "duration": { "type": "string", "enum": [ "once", "repeating", "forever" ], "description": "first payment only, some months, or every payment" }, "months": { "type": "integer", "description": "repeating: how many months (1–36)" }, "max_uses": { "type": "integer", "description": "uses in all (0 = unlimited)" }, "per_customer": { "type": "integer", "description": "uses per customer (0 = unlimited)" }, "starts": { "type": "string", "description": "first day, YYYY-MM-DD" }, "expires": { "type": "string", "description": "last day, YYYY-MM-DD" }, "packages": { "type": "array", "items": { "type": "string" }, "description": "package ids it is limited to (empty = all)" }, "periods": { "type": "array", "items": { "type": "string" }, "description": "billing periods it is limited to: month, year (empty = all)" }, "plans": { "type": "array", "items": { "type": "string" }, "description": "licence plan keys it is limited to (the publisher's server)" }, "new_only": { "type": "boolean", "description": "new customers only" }, "note": { "type": "string", "description": "a note for yourself" }, "applies": { "type": "string", "enum": [ "hosting", "licence", "all" ], "description": "what it is for (licence and all: the publisher's server)" } }, "required": [ "code", "value" ] }, "example": { "code": "example", "value": 1.5 } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": true } }, "/coupons/{id}": { "get": { "operationId": "getCoupon", "tags": [ "Billing" ], "summary": "One discount code (id or code)", "description": "Administrator tokens only.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": false }, "patch": { "operationId": "updateCoupon", "tags": [ "Billing" ], "summary": "Change a code's rules (limits, dates, packages, periods, plans, new customers only, note)", "description": "Administrator tokens only. Needs a \"Read & change\" token.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "max_uses": { "type": "integer", "description": "uses in all (0 = unlimited)" }, "per_customer": { "type": "integer", "description": "uses per customer (0 = unlimited)" }, "starts": { "type": "string", "description": "first day, YYYY-MM-DD" }, "expires": { "type": "string", "description": "last day, YYYY-MM-DD" }, "packages": { "type": "array", "items": { "type": "string" }, "description": "package ids it is limited to (empty = all)" }, "periods": { "type": "array", "items": { "type": "string" }, "description": "billing periods it is limited to: month, year (empty = all)" }, "plans": { "type": "array", "items": { "type": "string" }, "description": "licence plan keys it is limited to (the publisher's server)" }, "new_only": { "type": "boolean", "description": "new customers only" }, "note": { "type": "string", "description": "a note for yourself" } } }, "example": { "max_uses": 1, "per_customer": 1, "starts": "example", "expires": "example" } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": true }, "put": { "operationId": "updateCouponPut", "tags": [ "Billing" ], "summary": "Change a code's rules (limits, dates, packages, periods, plans, new customers only, note)", "description": "Administrator tokens only. Needs a \"Read & change\" token.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "max_uses": { "type": "integer", "description": "uses in all (0 = unlimited)" }, "per_customer": { "type": "integer", "description": "uses per customer (0 = unlimited)" }, "starts": { "type": "string", "description": "first day, YYYY-MM-DD" }, "expires": { "type": "string", "description": "last day, YYYY-MM-DD" }, "packages": { "type": "array", "items": { "type": "string" }, "description": "package ids it is limited to (empty = all)" }, "periods": { "type": "array", "items": { "type": "string" }, "description": "billing periods it is limited to: month, year (empty = all)" }, "plans": { "type": "array", "items": { "type": "string" }, "description": "licence plan keys it is limited to (the publisher's server)" }, "new_only": { "type": "boolean", "description": "new customers only" }, "note": { "type": "string", "description": "a note for yourself" } } }, "example": { "max_uses": 1, "per_customer": 1, "starts": "example", "expires": "example" } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": true }, "delete": { "operationId": "endCoupon", "tags": [ "Billing" ], "summary": "End a discount code (its uses stay in the report)", "description": "Administrator tokens only. Needs a \"Read & change\" token.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": true } }, "/announcements": { "get": { "operationId": "listAnnouncements", "tags": [ "Support" ], "summary": "Announcements: staff the ones they sent (with counts), a customer the ones sent to them", "description": "Any token.", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" }, "x-hf-generic": true }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" }, "x-hf-generic": true }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" }, "x-hf-generic": true }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" }, "x-hf-generic": true }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "type": "object" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ {} ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "any", "x-hf-write": false }, "post": { "operationId": "createAnnouncement", "tags": [ "Support" ], "summary": "Send or schedule an announcement", "description": "Administrator and reseller tokens. Needs a \"Read & change\" token. Send an Idempotency-Key header to retry safely.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": "string", "description": "1–150 characters" }, "body": { "type": "string", "description": "simple Markdown, up to 10,000 characters" }, "kind": { "type": "string", "enum": [ "news", "service" ], "description": "news (default) or service" }, "audience": { "type": "string", "enum": [ "all", "package", "reseller", "feature" ], "description": "who gets it (resellers: always their own customers)" }, "target": { "type": "string", "description": "the package id, reseller id or feature key of the audience" }, "banner": { "type": "boolean", "description": "show a banner on the overview (default true)" }, "email": { "type": "boolean", "description": "email it (default true)" }, "banner_until": { "type": "string", "description": "the banner's last day, YYYY-MM-DD (default 30 days)" }, "send_at": { "type": "string", "description": "when to send it, YYYY-MM-DD HH:MM UTC (empty = now)" } }, "required": [ "subject", "body" ] }, "example": { "subject": "example", "body": "example" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "staff", "x-hf-write": true } }, "/kb/search": { "get": { "operationId": "searchHelp", "tags": [ "Support" ], "summary": "Search the help articles the token's user may read", "description": "Any token.", "parameters": [ { "name": "q", "in": "query", "required": true, "description": "the words to search for", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "at most this many (1–20, default 5)", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" }, "x-hf-generic": true }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" }, "x-hf-generic": true }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" }, "x-hf-generic": true }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "type": "object" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ {} ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "any", "x-hf-write": false } }, "/accounts/{username}/team": { "get": { "operationId": "listTeamMembers", "tags": [ "Team" ], "summary": "The account's team members, the plan's limit (-1 = no limit) and how many are used", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "post": { "operationId": "inviteTeamMember", "tags": [ "Team" ], "summary": "Invite someone by email with a role; they choose their own password from the email's link", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token. Send an Idempotency-Key header to retry safely.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "their name (up to 80 characters)" }, "email": { "type": "string", "description": "their email address" }, "role": { "type": "string", "enum": [ "full", "sites", "webdns", "files", "email", "databases", "billing", "readonly", "custom" ], "description": "the role" }, "screens": { "type": "array", "items": { "type": "string" }, "description": "the screens of a custom role (routes)" } }, "required": [ "email", "role" ] }, "example": { "email": "example", "role": "full" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/team/{id}": { "get": { "operationId": "getTeamMember", "tags": [ "Team" ], "summary": "One team member", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "patch": { "operationId": "updateTeamMember", "tags": [ "Team" ], "summary": "Change a team member's role, or suspend them or let them in again", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "full", "sites", "webdns", "files", "email", "databases", "billing", "readonly", "custom" ], "description": "the new role" }, "screens": { "type": "array", "items": { "type": "string" }, "description": "the screens of a custom role (routes)" }, "status": { "type": "string", "enum": [ "active", "suspended" ], "description": "suspended signs them out; active lets them in again" } } }, "example": { "role": "full", "screens": [ "example" ], "status": "active" } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true }, "delete": { "operationId": "removeTeamMember", "tags": [ "Team" ], "summary": "Remove a team member (their passkeys and own API tokens go too)", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/resellers/{username}/domain": { "get": { "operationId": "getResellerDomain", "tags": [ "Resellers" ], "summary": "A reseller's own panel, Mail and files addresses with their last DNS and certificate check", "description": "Administrator and reseller tokens.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "staff", "x-hf-write": false } }, "/resellers/{username}/domain/check": { "post": { "operationId": "checkResellerDomain", "tags": [ "Resellers" ], "summary": "Check a reseller's own addresses (DNS and certificate) now", "description": "Administrator and reseller tokens. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "staff", "x-hf-write": true } }, "/abuse": { "get": { "operationId": "listAbuseComplaints", "tags": [ "Abuse desk" ], "summary": "Abuse complaints, newest first", "description": "Administrator and reseller tokens.", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "default: new and waiting", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "text in the subject, domain, IP, account or reporter", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" }, "x-hf-generic": true }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" }, "x-hf-generic": true }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "type": "object" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ {} ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "staff", "x-hf-write": false }, "post": { "operationId": "createAbuseComplaint", "tags": [ "Abuse desk" ], "summary": "Add a complaint (it is read and linked to an account like an email)", "description": "Administrator and reseller tokens. Needs a \"Read & change\" token. Send an Idempotency-Key header to retry safely.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "description": "the complaint's text" }, "kind": { "type": "string", "enum": [ "spam", "phishing", "malware", "copyright", "attack", "other" ], "description": "default: worked out" }, "subject": { "type": "string", "description": "a short line" }, "reporter_name": { "type": "string", "description": "who reported it" }, "reporter_email": { "type": "string", "description": "where to answer" }, "ip": { "type": "string", "description": "the IP address it is about" }, "domain": { "type": "string", "description": "the domain it is about" }, "url": { "type": "string", "description": "the web address it is about" }, "when": { "type": "string", "description": "when it happened (ISO 8601)" } }, "required": [ "body" ] }, "example": { "body": "example" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "staff", "x-hf-write": true } }, "/abuse/{id}": { "get": { "operationId": "getAbuseComplaint", "tags": [ "Abuse desk" ], "summary": "One complaint with its timeline", "description": "Administrator and reseller tokens.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "staff", "x-hf-write": false } }, "/abuse/{id}/status": { "post": { "operationId": "setAbuseComplaintStatus", "tags": [ "Abuse desk" ], "summary": "Set a complaint's status", "description": "Administrator and reseller tokens. Needs a \"Read & change\" token.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "new", "waiting", "resolved" ], "description": "new, waiting (for the customer) or resolved" } }, "required": [ "status" ] }, "example": { "status": "new" } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "staff", "x-hf-write": true } }, "/abuse/{id}/notes": { "post": { "operationId": "addAbuseComplaintNote", "tags": [ "Abuse desk" ], "summary": "Add a staff note to a complaint", "description": "Administrator and reseller tokens. Needs a \"Read & change\" token.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string", "description": "the note" } }, "required": [ "text" ] }, "example": { "text": "example" } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "staff", "x-hf-write": true } }, "/accounts/{username}/dns-zones/{zone}/dnssec": { "get": { "operationId": "getDnssec", "tags": [ "DNS" ], "summary": "DNSSEC of a zone: status, DS records for the registrar, keys", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "zone", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "post": { "operationId": "setDnssec", "tags": [ "DNS" ], "summary": "Turn DNSSEC of a zone on or off", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "zone", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "true to sign the zone, false to stop" } }, "required": [ "enabled" ] }, "example": { "enabled": true } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true }, "put": { "operationId": "setDnssecPut", "tags": [ "DNS" ], "summary": "Turn DNSSEC of a zone on or off", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "zone", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "true to sign the zone, false to stop" } }, "required": [ "enabled" ] }, "example": { "enabled": true } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/invoices": { "get": { "operationId": "listInvoices", "tags": [ "Billing" ], "summary": "Invoices, newest first (staff: every account they see; customers: their own)", "description": "Any token.", "parameters": [ { "name": "account", "in": "query", "required": false, "description": "only this account (staff)", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "only this status", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "first day, YYYY-MM-DD (default: the start of this quarter)", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "description": "last day, YYYY-MM-DD (default: today)", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" }, "x-hf-generic": true }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" }, "x-hf-generic": true }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" }, "x-hf-generic": true }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "type": "object" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ {} ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "any", "x-hf-write": false }, "post": { "operationId": "createInvoice", "tags": [ "Billing" ], "summary": "Make an invoice for an account", "description": "Administrator tokens only. Needs a \"Read & change\" token. Send an Idempotency-Key header to retry safely.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "account": { "type": "string", "description": "the customer's username" }, "lines": { "type": "array", "items": { "type": "string" }, "description": "objects with description, quantity (default 1) and unit_price" }, "due_days": { "type": "integer", "description": "days until it is due (0–90)" }, "notes": { "type": "string", "description": "printed on the invoice" }, "paid": { "type": "boolean", "description": "make it already paid" }, "send": { "type": "boolean", "description": "email it" }, "coupon": { "type": "string", "description": "a discount code" } }, "required": [ "account", "lines" ] }, "example": { "account": "example", "lines": [ "example" ] } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": true } }, "/invoices/{id}": { "get": { "operationId": "getInvoice", "tags": [ "Billing" ], "summary": "One invoice with its lines, VAT breakdown, seller and buyer details", "description": "Any token.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "any", "x-hf-write": false } }, "/tax-report": { "get": { "operationId": "getTaxReport", "tags": [ "Billing" ], "summary": "Tax report per currency, country, kind and rate (detail=1: every document)", "description": "Administrator tokens only.", "parameters": [ { "name": "from", "in": "query", "required": false, "description": "first day, YYYY-MM-DD (default: the start of this quarter)", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "description": "last day, YYYY-MM-DD (default: today)", "schema": { "type": "string" } }, { "name": "detail", "in": "query", "required": false, "description": "every invoice and credit note instead of the sums", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": false } }, "/dunning": { "get": { "operationId": "getDunning", "tags": [ "Billing" ], "summary": "Unpaid invoices and failed payments: open cases, totals per currency, age buckets", "description": "Administrator tokens only.", "parameters": [ { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": false } }, "/affiliates": { "get": { "operationId": "listAffiliates", "tags": [ "Billing" ], "summary": "The affiliates with their clicks, sign-ups, conversions and earnings", "description": "Administrator tokens only.", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" }, "x-hf-generic": true }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" }, "x-hf-generic": true }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" }, "x-hf-generic": true }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" }, "x-hf-generic": true }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "type": "object" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ {} ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": false } }, "/affiliates/{username}": { "get": { "operationId": "getAffiliate", "tags": [ "Billing" ], "summary": "One affiliate's numbers and balance", "description": "Administrator tokens only.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": false } }, "/affiliate": { "get": { "operationId": "getMyAffiliateStats", "tags": [ "Billing" ], "summary": "Your own affiliate numbers and balance (customer tokens)", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false } }, "/config-history": { "get": { "operationId": "listConfigHistory", "tags": [ "Server" ], "summary": "The server config files the panel changed, with how many versions are kept", "description": "Administrator tokens only.", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" }, "x-hf-generic": true }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" }, "x-hf-generic": true }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" }, "x-hf-generic": true }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" }, "x-hf-generic": true }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "type": "object" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ {} ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": false } }, "/config-history/versions": { "get": { "operationId": "listConfigVersions", "tags": [ "Server" ], "summary": "The kept versions of one config file, newest first (when, who, which command)", "description": "Administrator tokens only.", "parameters": [ { "name": "file", "in": "query", "required": true, "description": "the file's name in the history (enc from GET /config-history)", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" }, "x-hf-generic": true }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" }, "x-hf-generic": true }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" }, "x-hf-generic": true }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" }, "x-hf-generic": true }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "type": "object" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ {} ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": false } }, "/config-history/diff": { "get": { "operationId": "getConfigDiff", "tags": [ "Server" ], "summary": "The difference between two versions of a config file (unified diff, parsed rows)", "description": "Administrator tokens only.", "parameters": [ { "name": "file", "in": "query", "required": true, "description": "the file's name in the history (enc from GET /config-history)", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": true, "description": "a version id or current", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "description": "a version id or current (default)", "schema": { "type": "string" } }, { "name": "format", "in": "query", "required": false, "description": "rows (default) or html (a page with the text escaped)", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": false } }, "/accounts/{username}/dns-zones": { "get": { "operationId": "listDnsZones", "tags": [ "DNS" ], "summary": "The account's DNS zones", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" } }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/DnsZone" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ { "domain": "example", "dnssec": true, "records": "example" } ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false } }, "/accounts/{username}/dns-zones/{zone}": { "get": { "operationId": "getDnsZone", "tags": [ "DNS" ], "summary": "A zone with its records", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "zone", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/DnsZone" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "domain": "example", "dnssec": true, "records": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false } }, "/accounts/{username}/dns-zones/{zone}/records": { "post": { "operationId": "addDnsRecord", "tags": [ "DNS" ], "summary": "Add a record", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token. Send an Idempotency-Key header to retry safely.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "zone", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "@ for the zone itself, or the part before the zone (default @)" }, "type": { "type": "string", "enum": [ "A", "AAAA", "CNAME", "ALIAS", "MX", "TXT", "SRV", "CAA", "NS" ], "description": "the record type" }, "value": { "type": "string", "description": "the record's value" }, "ttl": { "type": "integer", "description": "seconds (default 3600)" }, "priority": { "type": "integer", "description": "MX and SRV" } }, "required": [ "type", "value" ] }, "example": { "type": "A", "value": "example" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/DnsRecord" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "name": "example", "type": "example", "value": "example", "ttl": 1, "priority": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/dns-zones/{zone}/records/{id}": { "patch": { "operationId": "updateDnsRecord", "tags": [ "DNS" ], "summary": "Change a record (fields left out keep their value)", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "zone", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "the name" }, "type": { "type": "string", "enum": [ "A", "AAAA", "CNAME", "ALIAS", "MX", "TXT", "SRV", "CAA", "NS" ], "description": "the record type" }, "value": { "type": "string", "description": "the value" }, "ttl": { "type": "integer", "description": "seconds" }, "priority": { "type": "integer", "description": "MX and SRV" } } }, "example": { "name": "example", "type": "A", "value": "example", "ttl": 1 } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/DnsRecord" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "name": "example", "type": "example", "value": "example", "ttl": 1, "priority": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true }, "put": { "operationId": "updateDnsRecordPut", "tags": [ "DNS" ], "summary": "Change a record (fields left out keep their value)", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "zone", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "the name" }, "type": { "type": "string", "enum": [ "A", "AAAA", "CNAME", "ALIAS", "MX", "TXT", "SRV", "CAA", "NS" ], "description": "the record type" }, "value": { "type": "string", "description": "the value" }, "ttl": { "type": "integer", "description": "seconds" }, "priority": { "type": "integer", "description": "MX and SRV" } } }, "example": { "name": "example", "type": "A", "value": "example", "ttl": 1 } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/DnsRecord" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "name": "example", "type": "example", "value": "example", "ttl": 1, "priority": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true }, "delete": { "operationId": "deleteDnsRecord", "tags": [ "DNS" ], "summary": "Delete a record", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "zone", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/mailboxes": { "get": { "operationId": "listMailboxes", "tags": [ "Email" ], "summary": "The account's mailboxes", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" } }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Mailbox" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ { "address": "example", "quota_mb": 1, "used_mb": 1, "send_only": true, "created_at": "example" } ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "post": { "operationId": "createMailbox", "tags": [ "Email" ], "summary": "Create a mailbox", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token. Send an Idempotency-Key header to retry safely.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "address": { "type": "string", "description": "the full address, e.g. info@example.com" }, "password": { "type": "string", "description": "empty = a random one, returned once" }, "quota_mb": { "type": "integer", "description": "0 = no limit (up to 102400)" } }, "required": [ "address" ] }, "example": { "address": "example" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/mailboxes/{address}": { "get": { "operationId": "getMailbox", "tags": [ "Email" ], "summary": "One mailbox", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "address", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/Mailbox" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "address": "example", "quota_mb": 1, "used_mb": 1, "send_only": true, "created_at": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "delete": { "operationId": "deleteMailbox", "tags": [ "Email" ], "summary": "Delete a mailbox and its messages", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "address", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true }, "patch": { "operationId": "updateMailbox", "tags": [ "Email" ], "summary": "Change a mailbox's password, quota and/or whether it only sends", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "address", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "password": { "type": "string", "description": "the new password" }, "quota_mb": { "type": "integer", "description": "0 = no limit (up to 102400)" }, "send_only": { "type": "boolean", "description": "it sends, mail to it is refused" } } }, "example": { "password": "example", "quota_mb": 1, "send_only": true } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/Mailbox" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "address": "example", "quota_mb": 1, "used_mb": 1, "send_only": true, "created_at": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/mailboxes/{address}/password": { "post": { "operationId": "setMailboxPassword", "tags": [ "Email" ], "summary": "Set a mailbox's password", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "address", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "password": { "type": "string", "description": "empty = a random one, returned once" } } }, "example": { "password": "example" } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true }, "put": { "operationId": "setMailboxPasswordPut", "tags": [ "Email" ], "summary": "Set a mailbox's password", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "address", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "password": { "type": "string", "description": "empty = a random one, returned once" } } }, "example": { "password": "example" } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/mailboxes/{address}/quota": { "post": { "operationId": "setMailboxQuota", "tags": [ "Email" ], "summary": "Set a mailbox's quota", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "address", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "quota_mb": { "type": "integer", "description": "0 = no limit (up to 102400)" } }, "required": [ "quota_mb" ] }, "example": { "quota_mb": 1 } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/Mailbox" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "address": "example", "quota_mb": 1, "used_mb": 1, "send_only": true, "created_at": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true }, "put": { "operationId": "setMailboxQuotaPut", "tags": [ "Email" ], "summary": "Set a mailbox's quota", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "address", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "quota_mb": { "type": "integer", "description": "0 = no limit (up to 102400)" } }, "required": [ "quota_mb" ] }, "example": { "quota_mb": 1 } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/Mailbox" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "address": "example", "quota_mb": 1, "used_mb": 1, "send_only": true, "created_at": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/mailboxes/{address}/autoresponder": { "post": { "operationId": "setAutoresponder", "tags": [ "Email" ], "summary": "Switch the autoresponder on", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "address", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": "string", "description": "the reply's subject" }, "body": { "type": "string", "description": "the reply's text" }, "days": { "type": "integer", "description": "days before the same sender gets it again (default 1)" }, "start": { "type": "string", "description": "first day, YYYY-MM-DD" }, "end": { "type": "string", "description": "last day, YYYY-MM-DD" } }, "required": [ "subject", "body" ] }, "example": { "subject": "example", "body": "example" } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true }, "put": { "operationId": "setAutoresponderPut", "tags": [ "Email" ], "summary": "Switch the autoresponder on", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "address", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": "string", "description": "the reply's subject" }, "body": { "type": "string", "description": "the reply's text" }, "days": { "type": "integer", "description": "days before the same sender gets it again (default 1)" }, "start": { "type": "string", "description": "first day, YYYY-MM-DD" }, "end": { "type": "string", "description": "last day, YYYY-MM-DD" } }, "required": [ "subject", "body" ] }, "example": { "subject": "example", "body": "example" } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true }, "delete": { "operationId": "removeAutoresponder", "tags": [ "Email" ], "summary": "Switch the autoresponder off", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "address", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/forwarders": { "get": { "operationId": "listForwarders", "tags": [ "Email" ], "summary": "The account's forwarders", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" } }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Forwarder" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ { "source": "example", "destinations": [], "created_at": "example" } ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "post": { "operationId": "addForwarder", "tags": [ "Email" ], "summary": "Add or replace a forwarder", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token. Send an Idempotency-Key header to retry safely.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "type": "string", "description": "the address, or *@example.com for anything else" }, "destinations": { "type": "array", "items": { "type": "string" }, "description": "1–10 addresses (or one text separated by commas)" } }, "required": [ "source", "destinations" ] }, "example": { "source": "example", "destinations": [ "example" ] } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/Forwarder" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "source": "example", "destinations": [], "created_at": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/forwarders/{source}": { "get": { "operationId": "getForwarder", "tags": [ "Email" ], "summary": "One forwarder", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "source", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/Forwarder" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "source": "example", "destinations": [], "created_at": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "delete": { "operationId": "deleteForwarder", "tags": [ "Email" ], "summary": "Remove a forwarder", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "source", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/mysql-databases": { "get": { "operationId": "listMysqlDatabases", "tags": [ "Databases" ], "summary": "The account's MySQL databases", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" } }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "type": "object" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ {} ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "post": { "operationId": "createMysqlDatabase", "tags": [ "Databases" ], "summary": "Create a MySQL database", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token. Send an Idempotency-Key header to retry safely.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "the name, with or without _" }, "user": { "type": "boolean", "description": "also make a user of the same name with all privileges (password returned once)" } }, "required": [ "name" ] }, "example": { "name": "example" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/mysql-databases/{database}": { "get": { "operationId": "getMysqlDatabase", "tags": [ "Databases" ], "summary": "One MySQL database", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "database", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "delete": { "operationId": "deleteMysqlDatabase", "tags": [ "Databases" ], "summary": "Drop a MySQL database", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "database", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/mysql-databases/{database}/grant": { "post": { "operationId": "grantMysql", "tags": [ "Databases" ], "summary": "Let a user use a database", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "database", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "string", "description": "the user" }, "privileges": { "type": "array", "items": { "type": "string" }, "description": "e.g. [\"SELECT\",\"INSERT\"]; left out = all" } }, "required": [ "user" ] }, "example": { "user": "example" } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/mysql-databases/{database}/revoke": { "post": { "operationId": "revokeMysql", "tags": [ "Databases" ], "summary": "Take a user's rights away", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "database", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "string", "description": "the user" } }, "required": [ "user" ] }, "example": { "user": "example" } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/mysql-users": { "get": { "operationId": "listMysqlUsers", "tags": [ "Databases" ], "summary": "The account's MySQL users", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" } }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "type": "object" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ {} ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "post": { "operationId": "createMysqlUser", "tags": [ "Databases" ], "summary": "Create a MySQL user", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token. Send an Idempotency-Key header to retry safely.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "the name, with or without _" }, "password": { "type": "string", "description": "empty = a random one, returned once" } }, "required": [ "name" ] }, "example": { "name": "example" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/mysql-users/{user}": { "get": { "operationId": "getMysqlUser", "tags": [ "Databases" ], "summary": "One MySQL user", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "delete": { "operationId": "deleteMysqlUser", "tags": [ "Databases" ], "summary": "Delete a MySQL user", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/mysql-users/{user}/password": { "post": { "operationId": "setMysqlUserPassword", "tags": [ "Databases" ], "summary": "Set a MySQL user's password", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "password": { "type": "string", "description": "empty = a random one, returned once" } } }, "example": { "password": "example" } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true }, "put": { "operationId": "setMysqlUserPasswordPut", "tags": [ "Databases" ], "summary": "Set a MySQL user's password", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "password": { "type": "string", "description": "empty = a random one, returned once" } } }, "example": { "password": "example" } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/postgres-databases": { "get": { "operationId": "listPostgresDatabases", "tags": [ "Databases" ], "summary": "The account's PostgreSQL databases", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" } }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "type": "object" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ {} ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "post": { "operationId": "createPostgresDatabase", "tags": [ "Databases" ], "summary": "Create a PostgreSQL database and its owner user", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token. Send an Idempotency-Key header to retry safely.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "the name, with or without _" } }, "required": [ "name" ] }, "example": { "name": "example" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/postgres-databases/{database}": { "get": { "operationId": "getPostgresDatabase", "tags": [ "Databases" ], "summary": "One PostgreSQL database", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "database", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "delete": { "operationId": "deletePostgresDatabase", "tags": [ "Databases" ], "summary": "Drop a PostgreSQL database", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "database", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/postgres-databases/{database}/password": { "post": { "operationId": "setPostgresPassword", "tags": [ "Databases" ], "summary": "Set the owner user's password", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "database", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "password": { "type": "string", "description": "empty = a random one, returned once" } } }, "example": { "password": "example" } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true }, "put": { "operationId": "setPostgresPasswordPut", "tags": [ "Databases" ], "summary": "Set the owner user's password", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "database", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "password": { "type": "string", "description": "empty = a random one, returned once" } } }, "example": { "password": "example" } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/ssl-certificates": { "get": { "operationId": "listCertificates", "tags": [ "SSL" ], "summary": "Each domain's certificate", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" } }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Certificate" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ { "domain": "example", "type": "example", "expires": "example", "days_left": 1, "issuer": "example", "names": "example", "force_https": true, "autossl": true, "autossl_note": "example" } ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false } }, "/accounts/{username}/ssl-certificates/{domain}": { "get": { "operationId": "getCertificate", "tags": [ "SSL" ], "summary": "One domain's certificate", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/Certificate" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "domain": "example", "type": "example", "expires": "example", "days_left": 1, "issuer": "example", "names": "example", "force_https": true, "autossl": true, "autossl_note": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "delete": { "operationId": "removeCertificate", "tags": [ "SSL" ], "summary": "Remove the certificate (AutoSSL stops for it)", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/DomainSSL" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "domain": "example", "ssl": true, "type": "example", "expires": "example", "force_https": true, "autossl": true } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/ssl-certificates/{domain}/issue": { "post": { "operationId": "issueCertificate", "tags": [ "SSL" ], "summary": "Issue a free certificate now", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/DomainSSL" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "domain": "example", "ssl": true, "type": "example", "expires": "example", "force_https": true, "autossl": true } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/ssl-certificates/{domain}/renew": { "post": { "operationId": "renewCertificate", "tags": [ "SSL" ], "summary": "Renew the certificate now", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/DomainSSL" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "domain": "example", "ssl": true, "type": "example", "expires": "example", "force_https": true, "autossl": true } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/ssl-certificates/{domain}/force-https": { "post": { "operationId": "setForceHttps", "tags": [ "SSL" ], "summary": "Always send visitors to https:// (or not)", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "on": { "type": "boolean", "description": "true = redirect to https://" } }, "required": [ "on" ] }, "example": { "on": true } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/DomainSSL" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "domain": "example", "ssl": true, "type": "example", "expires": "example", "force_https": true, "autossl": true } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true }, "put": { "operationId": "setForceHttpsPut", "tags": [ "SSL" ], "summary": "Always send visitors to https:// (or not)", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "on": { "type": "boolean", "description": "true = redirect to https://" } }, "required": [ "on" ] }, "example": { "on": true } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/DomainSSL" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "domain": "example", "ssl": true, "type": "example", "expires": "example", "force_https": true, "autossl": true } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/backups": { "get": { "operationId": "listBackups", "tags": [ "Backups" ], "summary": "The account's backups, newest first", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" } }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Backup" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ { "name": "example", "size": 1, "created_at": "example" } ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "post": { "operationId": "createBackup", "tags": [ "Backups" ], "summary": "Make a backup now", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token. Send an Idempotency-Key header to retry safely.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/Backup" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "name": "example", "size": 1, "created_at": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/backups/{backup}/restore": { "post": { "operationId": "restoreBackup", "tags": [ "Backups" ], "summary": "Restore all of one part of a backup", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "backup", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "what": { "type": "string", "enum": [ "all", "files", "databases", "mail", "cron" ], "description": "what to restore; what is there now is overwritten" } }, "required": [ "what" ] }, "example": { "what": "all" } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/backups/{backup}/link": { "post": { "operationId": "createBackupLink", "tags": [ "Backups" ], "summary": "A download link that works without signing in", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token. Send an Idempotency-Key header to retry safely.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "backup", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/backups/{backup}": { "get": { "operationId": "getBackup", "tags": [ "Backups" ], "summary": "One backup", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "backup", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/Backup" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "name": "example", "size": 1, "created_at": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "delete": { "operationId": "deleteBackup", "tags": [ "Backups" ], "summary": "Delete a backup", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "backup", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/ssh-keys": { "get": { "operationId": "listSSHKeys", "tags": [ "SSH keys" ], "summary": "The account's SSH public keys", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" } }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/SSHKey" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ { "id": 1, "name": "example", "type": "example", "bits": 1, "fingerprint": "example", "comment": "example", "weak": true, "created_at": "example" } ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "post": { "operationId": "addSSHKey", "tags": [ "SSH keys" ], "summary": "Add a public key (ed25519, ECDSA or RSA of 3072 bits or more)", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token. Send an Idempotency-Key header to retry safely.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "description": "the public key line (the .pub file)" }, "name": { "type": "string", "description": "a name (default: the key's comment)" } }, "required": [ "key" ] }, "example": { "key": "example" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/SSHKey" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "name": "example", "type": "example", "bits": 1, "fingerprint": "example", "comment": "example", "weak": true, "created_at": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/ssh-keys/{id}": { "get": { "operationId": "getSSHKey", "tags": [ "SSH keys" ], "summary": "One public key", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/SSHKey" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "name": "example", "type": "example", "bits": 1, "fingerprint": "example", "comment": "example", "weak": true, "created_at": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "delete": { "operationId": "deleteSSHKey", "tags": [ "SSH keys" ], "summary": "Remove a public key", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/cron-jobs": { "get": { "operationId": "listCronJobs", "tags": [ "Cron jobs" ], "summary": "The account's cron jobs", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" } }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CronJob" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ { "id": 1, "schedule": "example", "command": "example", "created_at": "example" } ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "post": { "operationId": "addCronJob", "tags": [ "Cron jobs" ], "summary": "Add a cron job (50 at most)", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token. Send an Idempotency-Key header to retry safely.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "schedule": { "type": "string", "description": "5 fields: minute hour day month weekday" }, "command": { "type": "string", "description": "one line, up to 900 characters" } }, "required": [ "schedule", "command" ] }, "example": { "schedule": "example", "command": "example" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/CronJob" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "schedule": "example", "command": "example", "created_at": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/cron-jobs/{id}": { "get": { "operationId": "getCronJob", "tags": [ "Cron jobs" ], "summary": "One cron job", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/CronJob" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "schedule": "example", "command": "example", "created_at": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "delete": { "operationId": "deleteCronJob", "tags": [ "Cron jobs" ], "summary": "Delete a cron job", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/ftp-accounts": { "get": { "operationId": "listFtpAccounts", "tags": [ "FTP" ], "summary": "The account's FTP accounts", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" } }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/FtpAccount" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ { "login": "example", "folder": "example", "quota_mb": 1, "created_at": "example" } ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "post": { "operationId": "createFtpAccount", "tags": [ "FTP" ], "summary": "Create an FTP account", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token. Send an Idempotency-Key header to retry safely.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "login": { "type": "string", "description": "name@domain, the domain one of the account's websites" }, "folder": { "type": "string", "description": "the folder inside web/ it may see (default all of web/)" }, "quota_mb": { "type": "integer", "description": "0 = no limit" }, "password": { "type": "string", "description": "empty = a random one, returned once" } }, "required": [ "login" ] }, "example": { "login": "example" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/ftp-accounts/{login}": { "get": { "operationId": "getFtpAccount", "tags": [ "FTP" ], "summary": "One FTP account", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "login", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/FtpAccount" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "login": "example", "folder": "example", "quota_mb": 1, "created_at": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "delete": { "operationId": "deleteFtpAccount", "tags": [ "FTP" ], "summary": "Delete an FTP account (its files stay)", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "login", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true }, "patch": { "operationId": "updateFtpAccount", "tags": [ "FTP" ], "summary": "Change an FTP account's password and/or quota", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "login", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "password": { "type": "string", "description": "the new password" }, "quota_mb": { "type": "integer", "description": "0 = no limit (up to 1048576)" } } }, "example": { "password": "example", "quota_mb": 1 } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/FtpAccount" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "login": "example", "folder": "example", "quota_mb": 1, "created_at": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/ftp-accounts/{login}/password": { "post": { "operationId": "setFtpPassword", "tags": [ "FTP" ], "summary": "Set an FTP account's password", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "login", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "password": { "type": "string", "description": "empty = a random one, returned once" } } }, "example": { "password": "example" } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true }, "put": { "operationId": "setFtpPasswordPut", "tags": [ "FTP" ], "summary": "Set an FTP account's password", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "login", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "password": { "type": "string", "description": "empty = a random one, returned once" } } }, "example": { "password": "example" } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/uptime-monitors": { "get": { "operationId": "listMonitors", "tags": [ "Uptime" ], "summary": "The account's uptime monitors", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" } }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Monitor" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ { "id": 1, "name": "example", "kind": "example", "target": "example", "url": "example", "host": "example", "port": 1, "interval_min": 1, "status": "example", "paused": true, "uptime_24h": 1.5, "uptime_30d": 1.5, "last_check": "example", "last_ms": 1, "last_error": "example", "ssl_expires": "example", "public": true } ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "post": { "operationId": "createMonitor", "tags": [ "Uptime" ], "summary": "Start watching a website, port or host", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token. Send an Idempotency-Key header to retry safely.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "http", "tcp", "ping" ], "description": "default http" }, "name": { "type": "string", "description": "shown on the screens and the status page" }, "url": { "type": "string", "description": "http: the address, e.g. https://example.com/shop" }, "host": { "type": "string", "description": "tcp and ping: a host name or public IP address" }, "port": { "type": "integer", "description": "tcp: the port" }, "interval_min": { "type": "integer", "description": "1, 5 or 15 minutes (not below the package's shortest)" }, "timeout": { "type": "integer", "description": "seconds, 5–30 (default 15)" }, "code_min": { "type": "integer", "description": "http: lowest status code that counts as up (default 200)" }, "code_max": { "type": "integer", "description": "http: highest (default 399)" }, "keyword": { "type": "string", "description": "http: a word that must be on the page" }, "keyword_absent": { "type": "boolean", "description": "http: the word must not be on the page instead" }, "follow_redirects": { "type": "boolean", "description": "http: follow up to 5 redirects (default true)" }, "ssl_days": { "type": "integer", "description": "http: warn this many days before the certificate ends (0 = never, default 14)" }, "remind_hours": { "type": "integer", "description": "remind every N hours while it is down (0 = never)" }, "contacts": { "type": "array", "items": { "type": "string" }, "description": "up to 5 more email addresses for alerts" }, "public": { "type": "boolean", "description": "show it on the account's status page" } } }, "example": { "kind": "http", "name": "example", "url": "example", "host": "example" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/Monitor" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "name": "example", "kind": "example", "target": "example", "url": "example", "host": "example", "port": 1, "interval_min": 1, "status": "example", "paused": true, "uptime_24h": 1.5, "uptime_30d": 1.5, "last_check": "example", "last_ms": 1, "last_error": "example", "ssl_expires": "example", "public": true } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/uptime-monitors/{id}": { "get": { "operationId": "getMonitorHistory", "tags": [ "Uptime" ], "summary": "A monitor with its response times and incidents", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "range", "in": "query", "required": false, "description": "default 24h", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "delete": { "operationId": "deleteMonitor", "tags": [ "Uptime" ], "summary": "Stop watching (its history goes too)", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/server/updates": { "get": { "operationId": "getServerUpdates", "tags": [ "Server" ], "summary": "Operating system updates: how many, when checked, the update log", "description": "Administrator tokens only.", "parameters": [ { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/ServerUpdates" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "updates": 1, "security": 1, "checked": "example", "running": true, "reboot_required": true, "os": "example", "kernel": "example", "log": [], "error": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": false } }, "/server/updates/check": { "post": { "operationId": "checkServerUpdates", "tags": [ "Server" ], "summary": "Check for updates now", "description": "Administrator tokens only. Needs a \"Read & change\" token.", "parameters": [ { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/ServerUpdates" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "updates": 1, "security": 1, "checked": "example", "running": true, "reboot_required": true, "os": "example", "kernel": "example", "log": [], "error": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": true } }, "/server/updates/apply": { "post": { "operationId": "applyServerUpdates", "tags": [ "Server" ], "summary": "Install the updates in the background (follow the log with GET /server/updates)", "description": "Administrator tokens only. Needs a \"Read & change\" token.", "parameters": [ { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/ServerUpdates" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "updates": 1, "security": 1, "checked": "example", "running": true, "reboot_required": true, "os": "example", "kernel": "example", "log": [], "error": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": true } }, "/firewall-rules": { "get": { "operationId": "listServerFirewallRules", "tags": [ "Firewall" ], "summary": "The firewall's rules", "description": "Administrator tokens only.", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" } }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/FirewallRule" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ { "id": 1, "to": "example", "action": "example", "from": "example", "ssh": true } ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": false }, "post": { "operationId": "createServerFirewallRule", "tags": [ "Firewall" ], "summary": "Open a port (action allow) or block an address or range (action block)", "description": "Administrator tokens only. Needs a \"Read & change\" token. Send an Idempotency-Key header to retry safely.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "allow", "block" ], "description": "allow or block" }, "port": { "type": "string", "description": "allow: 3306 or a range 6000:6100" }, "proto": { "type": "string", "enum": [ "tcp", "udp", "any" ], "description": "allow: tcp (default), udp or any" }, "ip": { "type": "string", "description": "block: an address or range like 203.0.113.0/24" } }, "required": [ "action" ] }, "example": { "action": "allow" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/FirewallRule" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "to": "example", "action": "example", "from": "example", "ssh": true } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": true } }, "/firewall-rules/{id}": { "get": { "operationId": "getServerFirewallRule", "tags": [ "Firewall" ], "summary": "One rule", "description": "Administrator tokens only.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/FirewallRule" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "to": "example", "action": "example", "from": "example", "ssh": true } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": false }, "delete": { "operationId": "deleteServerFirewallRule", "tags": [ "Firewall" ], "summary": "Remove a rule (the rule numbers move up after it)", "description": "Administrator tokens only. Needs a \"Read & change\" token.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": true } }, "/firewall-bans": { "get": { "operationId": "listFirewallBans", "tags": [ "Firewall" ], "summary": "The addresses fail2ban has banned", "description": "Administrator tokens only.", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" } }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/FirewallBan" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ { "ip": "example", "jail": "example" } ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": false } }, "/firewall-bans/{ip}": { "delete": { "operationId": "deleteFirewallBan", "tags": [ "Firewall" ], "summary": "Lift a ban", "description": "Administrator tokens only. Needs a \"Read & change\" token.", "parameters": [ { "name": "ip", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": true } }, "/ip-blocks": { "get": { "operationId": "listServerIpBlocks", "tags": [ "Firewall" ], "summary": "The addresses blocked from the whole server", "description": "Administrator tokens only.", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" } }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/IpBlock" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ { "id": 1, "ip": "example" } ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": false }, "post": { "operationId": "createServerIpBlock", "tags": [ "Firewall" ], "summary": "Block an address or range from the whole server", "description": "Administrator tokens only. Needs a \"Read & change\" token. Send an Idempotency-Key header to retry safely.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ip": { "type": "string", "description": "an address or range like 203.0.113.0/24" } }, "required": [ "ip" ] }, "example": { "ip": "example" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/IpBlock" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "ip": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": true } }, "/ip-blocks/{ip}": { "delete": { "operationId": "deleteServerIpBlock", "tags": [ "Firewall" ], "summary": "Unblock an address or range (write / in a range as %2F)", "description": "Administrator tokens only. Needs a \"Read & change\" token.", "parameters": [ { "name": "ip", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": true } }, "/activity-log": { "get": { "operationId": "listActivityLog", "tags": [ "Server" ], "summary": "The newest 500 lines of the activity log; q searches the account, action, detail and address", "description": "Administrator tokens only.", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "search text", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" } }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ActivityEntry" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ { "at": "example", "account": "example", "action": "example", "detail": "example", "ip": "example" } ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": false } }, "/staff": { "get": { "operationId": "listStaff", "tags": [ "Staff" ], "summary": "The administrator logins", "description": "Administrator tokens only.", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" } }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/StaffLogin" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ { "id": 1, "username": "example", "email": "example", "access": "example", "two_factor": true, "self": true } ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": false }, "post": { "operationId": "createStaff", "tags": [ "Staff" ], "summary": "Add an administrator login; it gets an email to choose its password. Full access needs a second administrator's approval when that is switched on (refused here)", "description": "Administrator tokens only. Needs a \"Read & change\" token. Send an Idempotency-Key header to retry safely.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "username": { "type": "string", "description": "3–32 lowercase letters, numbers, . _ -, starting with a letter" }, "email": { "type": "string", "description": "their email address" }, "access": { "type": "string", "enum": [ "read-only", "full" ], "description": "read-only (default) or full" } }, "required": [ "username", "email" ] }, "example": { "username": "example", "email": "example" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/StaffLogin" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "username": "example", "email": "example", "access": "example", "two_factor": true, "self": true } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": true } }, "/staff/{username}": { "get": { "operationId": "getStaff", "tags": [ "Staff" ], "summary": "One administrator login", "description": "Administrator tokens only.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/StaffLogin" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "username": "example", "email": "example", "access": "example", "two_factor": true, "self": true } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": false }, "patch": { "operationId": "updateStaff", "tags": [ "Staff" ], "summary": "Change a login's access", "description": "Administrator tokens only. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "access": { "type": "string", "enum": [ "read-only", "full" ], "description": "read-only or full" } }, "required": [ "access" ] }, "example": { "access": "read-only" } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/StaffLogin" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "username": "example", "email": "example", "access": "example", "two_factor": true, "self": true } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": true }, "delete": { "operationId": "deleteStaff", "tags": [ "Staff" ], "summary": "Remove an administrator login (at least one full one stays)", "description": "Administrator tokens only. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": true } }, "/staff/{username}/resend": { "post": { "operationId": "resendStaffInvitation", "tags": [ "Staff" ], "summary": "Email the login a new link to choose its password", "description": "Administrator tokens only. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": true } }, "/invoices/{id}/mark-paid": { "post": { "operationId": "markInvoicePaid", "tags": [ "Billing" ], "summary": "Mark an unpaid invoice made by hand paid; a receipt is emailed", "description": "Administrator tokens only. Needs a \"Read & change\" token.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": true } }, "/invoices/{id}/void": { "post": { "operationId": "voidInvoice", "tags": [ "Billing" ], "summary": "Void an invoice (its number stays used)", "description": "Administrator tokens only. Needs a \"Read & change\" token.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": true } }, "/invoices/{id}/send": { "post": { "operationId": "sendInvoice", "tags": [ "Billing" ], "summary": "Email the invoice again", "description": "Administrator tokens only. Needs a \"Read & change\" token.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": true } }, "/payments": { "get": { "operationId": "listPayments", "tags": [ "Billing" ], "summary": "Payments received, newest first: the paid invoices the token may see", "description": "Any token.", "parameters": [ { "name": "account", "in": "query", "required": false, "description": "only this account (staff)", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "first day, YYYY-MM-DD", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "description": "last day, YYYY-MM-DD", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" } }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ { "id": 1, "invoice": "example", "account": "example", "amount": 1.5, "currency": "example", "method": "example", "paid_at": "example" } ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "any", "x-hf-write": false } }, "/payments/{id}": { "get": { "operationId": "getPayment", "tags": [ "Billing" ], "summary": "One payment (by its invoice's id)", "description": "Any token.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/Payment" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "invoice": "example", "account": "example", "amount": 1.5, "currency": "example", "method": "example", "paid_at": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "any", "x-hf-write": false } }, "/products": { "get": { "operationId": "listProducts", "tags": [ "Billing" ], "summary": "The packages as they are sold, cheapest first (change them with /packages)", "description": "Administrator and reseller tokens.", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" } }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ { "id": 1, "name": "example", "price_month": 1.5, "disk_mb": 1, "max_domains": 1, "max_databases": 1, "max_mailboxes": 1, "trial_days": 1 } ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "staff", "x-hf-write": false } }, "/products/{id}": { "get": { "operationId": "getProduct", "tags": [ "Billing" ], "summary": "One product", "description": "Administrator and reseller tokens.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/Product" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "name": "example", "price_month": 1.5, "disk_mb": 1, "max_domains": 1, "max_databases": 1, "max_mailboxes": 1, "trial_days": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "staff", "x-hf-write": false } }, "/orders": { "get": { "operationId": "listOrders", "tags": [ "Billing" ], "summary": "Domain orders, newest first (staff: those of the accounts they see; customers: their own)", "description": "Any token.", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "only this status", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" } }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ { "id": 1, "kind": "example", "domain": "example", "years": 1, "amount": 1.5, "currency": "example", "status": "example", "account": "example", "invoice": "example", "error": "example", "created_at": "example", "done_at": "example" } ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "any", "x-hf-write": false } }, "/orders/{id}": { "get": { "operationId": "getOrder", "tags": [ "Billing" ], "summary": "One order", "description": "Any token.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/Order" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "kind": "example", "domain": "example", "years": 1, "amount": 1.5, "currency": "example", "status": "example", "account": "example", "invoice": "example", "error": "example", "created_at": "example", "done_at": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "any", "x-hf-write": false } }, "/accounts/{username}/git-repos": { "get": { "operationId": "listGitRepos", "tags": [ "Git" ], "summary": "The account's Git repositories", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" } }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/GitRepo" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ { "id": 1, "name": "example", "url": "example", "deploy": "example", "last_deploy": "example", "branch": "example", "branches": [], "remote": "example", "changes": 1, "commits": [] } ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "post": { "operationId": "createGitRepo", "tags": [ "Git" ], "summary": "Clone a repository (or start an empty one) into ~/web/repositories", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token. Send an Idempotency-Key header to retry safely.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "letters, numbers, . _ - (e.g. my-site)" }, "url": { "type": "string", "description": "an https:// clone address; empty starts an empty repository" }, "branch": { "type": "string", "description": "clone only this branch" }, "deploy": { "type": "string", "description": "the website folder inside web/ to deploy to, e.g. example.com/public_html" } }, "required": [ "name" ] }, "example": { "name": "example" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/GitRepo" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "deploy": "example.com/public_html", "id": 3, "last_deploy": null, "name": "my-site", "url": "https://github.com/you/site.git" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/git-repos/{name}": { "get": { "operationId": "getGitRepo", "tags": [ "Git" ], "summary": "One repository with its branch, branches, remote, changes and recent commits", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/GitRepo" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "name": "example", "url": "example", "deploy": "example", "last_deploy": "example", "branch": "example", "branches": [], "remote": "example", "changes": 1, "commits": [] } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "patch": { "operationId": "updateGitRepo", "tags": [ "Git" ], "summary": "Set the deploy folder (empty turns deploying off) and/or switch to another branch", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "deploy": { "type": "string", "description": "the website folder inside web/ (empty: no deploying)" }, "branch": { "type": "string", "description": "switch to this branch" } } }, "example": { "deploy": "example", "branch": "example" } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/GitRepo" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "name": "example", "url": "example", "deploy": "example", "last_deploy": "example", "branch": "example", "branches": [], "remote": "example", "changes": 1, "commits": [] } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true }, "delete": { "operationId": "deleteGitRepo", "tags": [ "Git" ], "summary": "Delete a repository (deployed files are kept)", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/git-repos/{name}/pull": { "post": { "operationId": "pullGitRepo", "tags": [ "Git" ], "summary": "Pull the repository's remote", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/GitRepo" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "name": "example", "url": "example", "deploy": "example", "last_deploy": "example", "branch": "example", "branches": [], "remote": "example", "changes": 1, "commits": [] } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/git-repos/{name}/deploy": { "post": { "operationId": "deployGitRepo", "tags": [ "Git" ], "summary": "Copy the repository into its deploy folder", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/GitRepo" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "name": "example", "url": "example", "deploy": "example", "last_deploy": "example", "branch": "example", "branches": [], "remote": "example", "changes": 1, "commits": [] } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/redis": { "get": { "operationId": "getRedis", "tags": [ "Redis" ], "summary": "The account's Redis cache: on or off, size, memory use, hit rate", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/RedisStatus" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "enabled": true, "running": true, "memory_mb": 1, "sizes": [], "version": "example", "used": "example", "keys": "example", "evicted": "example", "hit_rate": "example", "socket": "example", "wordpress": [] } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "put": { "operationId": "enableRedis", "tags": [ "Redis" ], "summary": "Switch Redis on, or change its size (within the package)", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "memory_mb": { "type": "integer", "description": "32, 64, 128 … up to the package's limit" } }, "required": [ "memory_mb" ] }, "example": { "memory_mb": 1 } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/RedisStatus" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "enabled": true, "running": true, "memory_mb": 1, "sizes": [], "version": "example", "used": "example", "keys": "example", "evicted": "example", "hit_rate": "example", "socket": "example", "wordpress": [] } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true }, "delete": { "operationId": "disableRedis", "tags": [ "Redis" ], "summary": "Switch Redis off and free its memory", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/RedisStatus" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "enabled": true, "running": true, "memory_mb": 1, "sizes": [], "version": "example", "used": "example", "keys": "example", "evicted": "example", "hit_rate": "example", "socket": "example", "wordpress": [] } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/redis/flush": { "post": { "operationId": "flushRedis", "tags": [ "Redis" ], "summary": "Empty the cache", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/redis/wordpress/{id}": { "put": { "operationId": "setRedisWordPress", "tags": [ "Redis" ], "summary": "Turn a WordPress site's Redis object cache on or off", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "on or off" } }, "required": [ "enabled" ] }, "example": { "enabled": true } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/RedisStatus" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "enabled": true, "running": true, "memory_mb": 1, "sizes": [], "version": "example", "used": "example", "keys": "example", "evicted": "example", "hit_rate": "example", "socket": "example", "wordpress": [] } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/memcached": { "get": { "operationId": "getMemcached", "tags": [ "Memcached" ], "summary": "The account's Memcached: on or off, size, memory use, hit rate", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/MemcachedStatus" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "enabled": true, "running": true, "memory_mb": 1, "sizes": [], "version": "example", "used": "example", "items": "example", "evicted": "example", "hit_rate": "example", "socket": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "put": { "operationId": "enableMemcached", "tags": [ "Memcached" ], "summary": "Switch Memcached on, or change its size (within the package)", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "memory_mb": { "type": "integer", "description": "16, 32, 64 … up to the package's limit" } }, "required": [ "memory_mb" ] }, "example": { "memory_mb": 1 } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/MemcachedStatus" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "enabled": true, "running": true, "memory_mb": 1, "sizes": [], "version": "example", "used": "example", "items": "example", "evicted": "example", "hit_rate": "example", "socket": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true }, "delete": { "operationId": "disableMemcached", "tags": [ "Memcached" ], "summary": "Switch Memcached off and free its memory", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/MemcachedStatus" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "enabled": true, "running": true, "memory_mb": 1, "sizes": [], "version": "example", "used": "example", "items": "example", "evicted": "example", "hit_rate": "example", "socket": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/memcached/flush": { "post": { "operationId": "flushMemcached", "tags": [ "Memcached" ], "summary": "Empty the cache", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/docker-catalog": { "get": { "operationId": "listDockerCatalog", "tags": [ "Docker" ], "summary": "The apps that can be installed", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" } }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/DockerCatalogApp" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ { "key": "example", "title": "example", "description": "example", "memory_mb": 1 } ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false } }, "/accounts/{username}/docker-apps": { "get": { "operationId": "listDockerApps", "tags": [ "Docker" ], "summary": "The account's Docker apps", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" } }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/DockerApp" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ { "name": "example", "app": "example", "title": "example", "domain": "example", "status": "example", "running": true, "memory_mb": 1, "password": "example" } ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "post": { "operationId": "installDockerApp", "tags": [ "Docker" ], "summary": "Install an app from the catalogue on one of the account's domains (within the package's limit)", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token. Send an Idempotency-Key header to retry safely.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "app": { "type": "string", "description": "its key in the catalogue" }, "domain": { "type": "string", "description": "the domain or subdomain to serve it on" } }, "required": [ "app", "domain" ] }, "example": { "app": "example", "domain": "example" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/DockerApp" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "app": "uptime-kuma", "domain": "blog.example.com", "memory_mb": 0, "name": "kumablog", "password": "3f9a1c2b7d", "running": false, "status": "Starting", "title": "Uptime Kuma" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/docker-apps/{name}": { "get": { "operationId": "getDockerApp", "tags": [ "Docker" ], "summary": "One Docker app", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/DockerApp" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "name": "example", "app": "example", "title": "example", "domain": "example", "status": "example", "running": true, "memory_mb": 1, "password": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "delete": { "operationId": "deleteDockerApp", "tags": [ "Docker" ], "summary": "Remove an app (its data folder is kept; purge=1 deletes the data too)", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "purge", "in": "query", "required": false, "description": "delete its data too", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/docker-apps/{name}/logs": { "get": { "operationId": "getDockerAppLogs", "tags": [ "Docker" ], "summary": "An app's log", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false } }, "/accounts/{username}/docker-apps/{name}/start": { "post": { "operationId": "startDockerApp", "tags": [ "Docker" ], "summary": "Start an app", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/DockerApp" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "name": "example", "app": "example", "title": "example", "domain": "example", "status": "example", "running": true, "memory_mb": 1, "password": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/docker-apps/{name}/stop": { "post": { "operationId": "stopDockerApp", "tags": [ "Docker" ], "summary": "Stop an app", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/DockerApp" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "name": "example", "app": "example", "title": "example", "domain": "example", "status": "example", "running": true, "memory_mb": 1, "password": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/docker-apps/{name}/restart": { "post": { "operationId": "restartDockerApp", "tags": [ "Docker" ], "summary": "Restart an app", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/DockerApp" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "name": "example", "app": "example", "title": "example", "domain": "example", "status": "example", "running": true, "memory_mb": 1, "password": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/logs": { "get": { "operationId": "getLogs", "tags": [ "Logs" ], "summary": "A website's access, error or PHP log (the last 300 lines), the explained errors, or the raw files in ~/logs", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "description": "errors (default), access, error, php or raw", "schema": { "type": "string" } }, { "name": "domain", "in": "query", "required": false, "description": "the website (access and error logs)", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/LogView" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "type": "example", "domain": "example", "file": "example", "error": "example", "size": "example", "lines": [], "groups": [], "files": [] } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false } }, "/accounts/{username}/node-apps": { "get": { "operationId": "listNodeApps", "tags": [ "Node.js apps" ], "summary": "The account's Node.js apps", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" } }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/App" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ { "id": 1, "name": "example", "domain": "example", "root": "example", "state": "example", "port": 1, "env": {}, "created_at": "example", "kind": "example", "mode": "example", "node": "example", "install": "example", "build": "example", "start_cmd": "example", "outdir": "example", "framework": "example", "entry": "example", "server": "example", "python": "example", "workers": 1 } ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "post": { "operationId": "createNodeApp", "tags": [ "Node.js apps" ], "summary": "Create a Node.js app on one of the account's websites", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token. Send an Idempotency-Key header to retry safely.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "letters, numbers, - and _ (e.g. shop)" }, "domain": { "type": "string", "description": "the website it takes over (one app per main domain)" }, "root": { "type": "string", "description": "its folder in the account, e.g. apps/shop" }, "node": { "type": "string", "description": "an installed Node.js major version, e.g. 22" }, "mode": { "type": "string", "enum": [ "production", "development" ], "description": "production (default) or development" }, "kind": { "type": "string", "enum": [ "server", "static" ], "description": "server (default) or static" }, "install": { "type": "string", "enum": [ "npm", "npm-ci", "yarn", "pnpm", "none" ], "description": "how dependencies are installed (default npm)" }, "build": { "type": "string", "description": "the package.json script that builds it, e.g. build" }, "start_cmd": { "type": "string", "description": "server: node, npm, npx, yarn or pnpm and plain words, e.g. npm start" }, "outdir": { "type": "string", "description": "static: the build folder inside the app folder, e.g. dist" }, "framework": { "type": "string", "description": "what it is (informational)" }, "env": { "type": "object", "description": "environment variables, NAME: value (up to 30; replaces the earlier ones)" } }, "required": [ "name", "domain", "root" ] }, "example": { "name": "example", "domain": "example", "root": "example" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/App" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "name": "example", "domain": "example", "root": "example", "state": "example", "port": 1, "env": {}, "created_at": "example", "kind": "example", "mode": "example", "node": "example", "install": "example", "build": "example", "start_cmd": "example", "outdir": "example", "framework": "example", "entry": "example", "server": "example", "python": "example", "workers": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/node-apps/{name}": { "get": { "operationId": "getNodeApp", "tags": [ "Node.js apps" ], "summary": "One Node.js app", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/App" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "name": "example", "domain": "example", "root": "example", "state": "example", "port": 1, "env": {}, "created_at": "example", "kind": "example", "mode": "example", "node": "example", "install": "example", "build": "example", "start_cmd": "example", "outdir": "example", "framework": "example", "entry": "example", "server": "example", "python": "example", "workers": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "patch": { "operationId": "updateNodeApp", "tags": [ "Node.js apps" ], "summary": "Change a Node.js app's settings (what you leave out stays as it is) and restart it", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "description": "the website it takes over (one app per main domain)" }, "root": { "type": "string", "description": "its folder in the account, e.g. apps/shop" }, "node": { "type": "string", "description": "an installed Node.js major version, e.g. 22" }, "mode": { "type": "string", "enum": [ "production", "development" ], "description": "production (default) or development" }, "kind": { "type": "string", "enum": [ "server", "static" ], "description": "server (default) or static" }, "install": { "type": "string", "enum": [ "npm", "npm-ci", "yarn", "pnpm", "none" ], "description": "how dependencies are installed (default npm)" }, "build": { "type": "string", "description": "the package.json script that builds it, e.g. build" }, "start_cmd": { "type": "string", "description": "server: node, npm, npx, yarn or pnpm and plain words, e.g. npm start" }, "outdir": { "type": "string", "description": "static: the build folder inside the app folder, e.g. dist" }, "framework": { "type": "string", "description": "what it is (informational)" }, "env": { "type": "object", "description": "environment variables, NAME: value (up to 30; replaces the earlier ones)" } } }, "example": { "domain": "example", "root": "example", "node": "example", "mode": "production" } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/App" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "name": "example", "domain": "example", "root": "example", "state": "example", "port": 1, "env": {}, "created_at": "example", "kind": "example", "mode": "example", "node": "example", "install": "example", "build": "example", "start_cmd": "example", "outdir": "example", "framework": "example", "entry": "example", "server": "example", "python": "example", "workers": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true }, "delete": { "operationId": "deleteNodeApp", "tags": [ "Node.js apps" ], "summary": "Remove a Node.js app (its files are kept; the website serves its own folder again)", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/node-apps/{name}/start": { "post": { "operationId": "startNodeApp", "tags": [ "Node.js apps" ], "summary": "Start a Node.js app", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/App" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "name": "example", "domain": "example", "root": "example", "state": "example", "port": 1, "env": {}, "created_at": "example", "kind": "example", "mode": "example", "node": "example", "install": "example", "build": "example", "start_cmd": "example", "outdir": "example", "framework": "example", "entry": "example", "server": "example", "python": "example", "workers": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/node-apps/{name}/stop": { "post": { "operationId": "stopNodeApp", "tags": [ "Node.js apps" ], "summary": "Stop a Node.js app", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/App" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "name": "example", "domain": "example", "root": "example", "state": "example", "port": 1, "env": {}, "created_at": "example", "kind": "example", "mode": "example", "node": "example", "install": "example", "build": "example", "start_cmd": "example", "outdir": "example", "framework": "example", "entry": "example", "server": "example", "python": "example", "workers": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/node-apps/{name}/restart": { "post": { "operationId": "restartNodeApp", "tags": [ "Node.js apps" ], "summary": "Restart a Node.js app", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/App" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "name": "example", "domain": "example", "root": "example", "state": "example", "port": 1, "env": {}, "created_at": "example", "kind": "example", "mode": "example", "node": "example", "install": "example", "build": "example", "start_cmd": "example", "outdir": "example", "framework": "example", "entry": "example", "server": "example", "python": "example", "workers": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/node-apps/{name}/build": { "post": { "operationId": "buildNodeApp", "tags": [ "Node.js apps" ], "summary": "Build and deploy a Node.js app (install, build, restart)", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/App" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "name": "example", "domain": "example", "root": "example", "state": "example", "port": 1, "env": {}, "created_at": "example", "kind": "example", "mode": "example", "node": "example", "install": "example", "build": "example", "start_cmd": "example", "outdir": "example", "framework": "example", "entry": "example", "server": "example", "python": "example", "workers": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/python-apps": { "get": { "operationId": "listPythonApps", "tags": [ "Python apps" ], "summary": "The account's Python apps", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" } }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/App" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ { "id": 1, "name": "example", "domain": "example", "root": "example", "state": "example", "port": 1, "env": {}, "created_at": "example", "kind": "example", "mode": "example", "node": "example", "install": "example", "build": "example", "start_cmd": "example", "outdir": "example", "framework": "example", "entry": "example", "server": "example", "python": "example", "workers": 1 } ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "post": { "operationId": "createPythonApp", "tags": [ "Python apps" ], "summary": "Create a Python app on one of the account's websites", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token. Send an Idempotency-Key header to retry safely.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "letters, numbers, - and _ (e.g. shop)" }, "domain": { "type": "string", "description": "the website it takes over (one app per main domain)" }, "root": { "type": "string", "description": "its folder in the account, e.g. apps/shop" }, "entry": { "type": "string", "description": "module:object, e.g. app:app (Flask), mysite.wsgi:application (Django), main:app (FastAPI); default app:app" }, "server": { "type": "string", "enum": [ "wsgi", "asgi" ], "description": "wsgi (default) or asgi" }, "python": { "type": "string", "description": "an installed Python version, e.g. 3.12" }, "workers": { "type": "integer", "description": "1–8 (default 2)" }, "env": { "type": "object", "description": "environment variables, NAME: value (up to 30; replaces the earlier ones)" } }, "required": [ "name", "domain", "root" ] }, "example": { "name": "example", "domain": "example", "root": "example" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/App" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "name": "example", "domain": "example", "root": "example", "state": "example", "port": 1, "env": {}, "created_at": "example", "kind": "example", "mode": "example", "node": "example", "install": "example", "build": "example", "start_cmd": "example", "outdir": "example", "framework": "example", "entry": "example", "server": "example", "python": "example", "workers": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/python-apps/{name}": { "get": { "operationId": "getPythonApp", "tags": [ "Python apps" ], "summary": "One Python app", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/App" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "name": "example", "domain": "example", "root": "example", "state": "example", "port": 1, "env": {}, "created_at": "example", "kind": "example", "mode": "example", "node": "example", "install": "example", "build": "example", "start_cmd": "example", "outdir": "example", "framework": "example", "entry": "example", "server": "example", "python": "example", "workers": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "patch": { "operationId": "updatePythonApp", "tags": [ "Python apps" ], "summary": "Change a Python app's settings (what you leave out stays as it is) and restart it", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "description": "the website it takes over (one app per main domain)" }, "root": { "type": "string", "description": "its folder in the account, e.g. apps/shop" }, "entry": { "type": "string", "description": "module:object, e.g. app:app (Flask), mysite.wsgi:application (Django), main:app (FastAPI); default app:app" }, "server": { "type": "string", "enum": [ "wsgi", "asgi" ], "description": "wsgi (default) or asgi" }, "python": { "type": "string", "description": "an installed Python version, e.g. 3.12" }, "workers": { "type": "integer", "description": "1–8 (default 2)" }, "env": { "type": "object", "description": "environment variables, NAME: value (up to 30; replaces the earlier ones)" } } }, "example": { "domain": "example", "root": "example", "entry": "example", "server": "wsgi" } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/App" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "name": "example", "domain": "example", "root": "example", "state": "example", "port": 1, "env": {}, "created_at": "example", "kind": "example", "mode": "example", "node": "example", "install": "example", "build": "example", "start_cmd": "example", "outdir": "example", "framework": "example", "entry": "example", "server": "example", "python": "example", "workers": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true }, "delete": { "operationId": "deletePythonApp", "tags": [ "Python apps" ], "summary": "Remove a Python app (its files are kept; the website serves its own folder again)", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/python-apps/{name}/start": { "post": { "operationId": "startPythonApp", "tags": [ "Python apps" ], "summary": "Start a Python app", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/App" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "name": "example", "domain": "example", "root": "example", "state": "example", "port": 1, "env": {}, "created_at": "example", "kind": "example", "mode": "example", "node": "example", "install": "example", "build": "example", "start_cmd": "example", "outdir": "example", "framework": "example", "entry": "example", "server": "example", "python": "example", "workers": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/python-apps/{name}/stop": { "post": { "operationId": "stopPythonApp", "tags": [ "Python apps" ], "summary": "Stop a Python app", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/App" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "name": "example", "domain": "example", "root": "example", "state": "example", "port": 1, "env": {}, "created_at": "example", "kind": "example", "mode": "example", "node": "example", "install": "example", "build": "example", "start_cmd": "example", "outdir": "example", "framework": "example", "entry": "example", "server": "example", "python": "example", "workers": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/python-apps/{name}/restart": { "post": { "operationId": "restartPythonApp", "tags": [ "Python apps" ], "summary": "Restart a Python app", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/App" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "name": "example", "domain": "example", "root": "example", "state": "example", "port": 1, "env": {}, "created_at": "example", "kind": "example", "mode": "example", "node": "example", "install": "example", "build": "example", "start_cmd": "example", "outdir": "example", "framework": "example", "entry": "example", "server": "example", "python": "example", "workers": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/python-apps/{name}/setup": { "post": { "operationId": "setupPythonApp", "tags": [ "Python apps" ], "summary": "Set a Python app up (install its packages) and (re)start it", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/App" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "name": "example", "domain": "example", "root": "example", "state": "example", "port": 1, "env": {}, "created_at": "example", "kind": "example", "mode": "example", "node": "example", "install": "example", "build": "example", "start_cmd": "example", "outdir": "example", "framework": "example", "entry": "example", "server": "example", "python": "example", "workers": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/ruby-apps": { "get": { "operationId": "listRubyApps", "tags": [ "Ruby apps" ], "summary": "The account's Ruby apps", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" } }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/App" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ { "id": 1, "name": "example", "domain": "example", "root": "example", "state": "example", "port": 1, "env": {}, "created_at": "example", "kind": "example", "mode": "example", "node": "example", "install": "example", "build": "example", "start_cmd": "example", "outdir": "example", "framework": "example", "entry": "example", "server": "example", "python": "example", "workers": 1 } ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "post": { "operationId": "createRubyApp", "tags": [ "Ruby apps" ], "summary": "Create a Ruby app on one of the account's websites", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token. Send an Idempotency-Key header to retry safely.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "letters, numbers, - and _ (e.g. shop)" }, "domain": { "type": "string", "description": "the website it takes over (one app per main domain)" }, "root": { "type": "string", "description": "its folder in the account, e.g. apps/shop" }, "entry": { "type": "string", "description": "the rackup file, e.g. config.ru (default)" }, "workers": { "type": "integer", "description": "0–8" }, "env": { "type": "object", "description": "environment variables, NAME: value (up to 30; replaces the earlier ones)" } }, "required": [ "name", "domain", "root" ] }, "example": { "name": "example", "domain": "example", "root": "example" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/App" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "name": "example", "domain": "example", "root": "example", "state": "example", "port": 1, "env": {}, "created_at": "example", "kind": "example", "mode": "example", "node": "example", "install": "example", "build": "example", "start_cmd": "example", "outdir": "example", "framework": "example", "entry": "example", "server": "example", "python": "example", "workers": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/ruby-apps/{name}": { "get": { "operationId": "getRubyApp", "tags": [ "Ruby apps" ], "summary": "One Ruby app", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/App" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "name": "example", "domain": "example", "root": "example", "state": "example", "port": 1, "env": {}, "created_at": "example", "kind": "example", "mode": "example", "node": "example", "install": "example", "build": "example", "start_cmd": "example", "outdir": "example", "framework": "example", "entry": "example", "server": "example", "python": "example", "workers": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "patch": { "operationId": "updateRubyApp", "tags": [ "Ruby apps" ], "summary": "Change a Ruby app's settings (what you leave out stays as it is) and restart it", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "description": "the website it takes over (one app per main domain)" }, "root": { "type": "string", "description": "its folder in the account, e.g. apps/shop" }, "entry": { "type": "string", "description": "the rackup file, e.g. config.ru (default)" }, "workers": { "type": "integer", "description": "0–8" }, "env": { "type": "object", "description": "environment variables, NAME: value (up to 30; replaces the earlier ones)" } } }, "example": { "domain": "example", "root": "example", "entry": "example", "workers": 1 } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/App" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "name": "example", "domain": "example", "root": "example", "state": "example", "port": 1, "env": {}, "created_at": "example", "kind": "example", "mode": "example", "node": "example", "install": "example", "build": "example", "start_cmd": "example", "outdir": "example", "framework": "example", "entry": "example", "server": "example", "python": "example", "workers": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true }, "delete": { "operationId": "deleteRubyApp", "tags": [ "Ruby apps" ], "summary": "Remove a Ruby app (its files are kept; the website serves its own folder again)", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/ruby-apps/{name}/start": { "post": { "operationId": "startRubyApp", "tags": [ "Ruby apps" ], "summary": "Start a Ruby app", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/App" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "name": "example", "domain": "example", "root": "example", "state": "example", "port": 1, "env": {}, "created_at": "example", "kind": "example", "mode": "example", "node": "example", "install": "example", "build": "example", "start_cmd": "example", "outdir": "example", "framework": "example", "entry": "example", "server": "example", "python": "example", "workers": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/ruby-apps/{name}/stop": { "post": { "operationId": "stopRubyApp", "tags": [ "Ruby apps" ], "summary": "Stop a Ruby app", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/App" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "name": "example", "domain": "example", "root": "example", "state": "example", "port": 1, "env": {}, "created_at": "example", "kind": "example", "mode": "example", "node": "example", "install": "example", "build": "example", "start_cmd": "example", "outdir": "example", "framework": "example", "entry": "example", "server": "example", "python": "example", "workers": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/ruby-apps/{name}/restart": { "post": { "operationId": "restartRubyApp", "tags": [ "Ruby apps" ], "summary": "Restart a Ruby app", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/App" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "name": "example", "domain": "example", "root": "example", "state": "example", "port": 1, "env": {}, "created_at": "example", "kind": "example", "mode": "example", "node": "example", "install": "example", "build": "example", "start_cmd": "example", "outdir": "example", "framework": "example", "entry": "example", "server": "example", "python": "example", "workers": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/ruby-apps/{name}/setup": { "post": { "operationId": "setupRubyApp", "tags": [ "Ruby apps" ], "summary": "Set a Ruby app up (install its packages) and (re)start it", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/App" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "name": "example", "domain": "example", "root": "example", "state": "example", "port": 1, "env": {}, "created_at": "example", "kind": "example", "mode": "example", "node": "example", "install": "example", "build": "example", "start_cmd": "example", "outdir": "example", "framework": "example", "entry": "example", "server": "example", "python": "example", "workers": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/ip-blocker": { "get": { "operationId": "listAccountBlocks", "tags": [ "Firewall rules" ], "summary": "The addresses blocked on every website of the account (the IP blocker), oldest first", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" } }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/AccountBlock" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ { "id": 1, "cidr": "example", "note": "example", "expires_at": "example", "created_at": "example" } ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "post": { "operationId": "createAccountBlock", "tags": [ "Firewall rules" ], "summary": "Block an address or range on every website of the account", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token. Send an Idempotency-Key header to retry safely.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cidr": { "type": "string", "description": "an address like 203.0.113.9 or a range like 203.0.113.0/24 (IPv4 /8 or smaller, IPv6 /16 or smaller)" }, "note": { "type": "string", "description": "a note (up to 200 characters)" }, "expires": { "type": "string", "enum": [ "1h", "1d", "7d", "30d", "never" ], "description": "when the block ends (default never)" }, "confirm": { "type": "boolean", "description": "block it even though it covers the address the request comes from" } }, "required": [ "cidr" ] }, "example": { "cidr": "example" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/AccountBlock" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "cidr": "203.0.113.0/24", "created_at": "2026-11-02 10:00:00", "expires_at": "2026-11-09 10:00:00", "id": 4, "note": "login attempts" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/ip-blocker/{id}": { "delete": { "operationId": "deleteAccountBlock", "tags": [ "Firewall rules" ], "summary": "Unblock an address of the IP blocker", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/autoresponders": { "get": { "operationId": "listAutoresponders", "tags": [ "Email" ], "summary": "The mailboxes that have an autoresponder", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" } }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Autoresponder" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ { "address": "example", "enabled": true, "subject": "example", "body": "example", "days": 1, "start": "example", "end": "example" } ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false } }, "/accounts/{username}/autoresponders/{address}": { "get": { "operationId": "getAutoresponder", "tags": [ "Email" ], "summary": "A mailbox's autoresponder (enabled false when it has none)", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "address", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/Autoresponder" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "address": "example", "enabled": true, "subject": "example", "body": "example", "days": 1, "start": "example", "end": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "put": { "operationId": "setAutoresponderRest", "tags": [ "Email" ], "summary": "Switch a mailbox's autoresponder on", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "address", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": "string", "description": "the reply's subject" }, "body": { "type": "string", "description": "the reply's text" }, "days": { "type": "integer", "description": "days before the same sender gets it again (default 1)" }, "start": { "type": "string", "description": "first day, YYYY-MM-DD" }, "end": { "type": "string", "description": "last day, YYYY-MM-DD" } }, "required": [ "subject", "body" ] }, "example": { "subject": "example", "body": "example" } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/Autoresponder" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "address": "example", "enabled": true, "subject": "example", "body": "example", "days": 1, "start": "example", "end": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true }, "delete": { "operationId": "removeAutoresponderRest", "tags": [ "Email" ], "summary": "Switch a mailbox's autoresponder off", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "address", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/databases": { "get": { "operationId": "listDatabases", "tags": [ "Databases" ], "summary": "The account's MySQL and PostgreSQL databases together", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "engine", "in": "query", "required": false, "description": "only this engine", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" } }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Database" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ { "name": "example", "engine": "example", "user": "example", "created_at": "example" } ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "post": { "operationId": "createDatabase", "tags": [ "Databases" ], "summary": "Create a database (within the package's limit); postgres also makes its owner user and answers its password", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token. Send an Idempotency-Key header to retry safely.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "the name after the account's prefix" }, "engine": { "type": "string", "enum": [ "mysql", "postgres" ], "description": "mysql (default) or postgres" }, "user": { "type": "boolean", "description": "mysql: also create a user of the same name" } }, "required": [ "name" ] }, "example": { "name": "example" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/databases/{name}": { "get": { "operationId": "getDatabase", "tags": [ "Databases" ], "summary": "One database", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "engine", "in": "query", "required": false, "description": "mysql or postgres (default: the first that has it)", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/Database" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "name": "example", "engine": "example", "user": "example", "created_at": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "delete": { "operationId": "deleteDatabase", "tags": [ "Databases" ], "summary": "Delete a database and what is in it", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "engine", "in": "query", "required": false, "description": "mysql (default) or postgres", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/database-users": { "get": { "operationId": "listDatabaseUsers", "tags": [ "Databases" ], "summary": "The account's MySQL users", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" } }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "type": "object" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ {} ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "post": { "operationId": "createDatabaseUser", "tags": [ "Databases" ], "summary": "Create a MySQL user", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token. Send an Idempotency-Key header to retry safely.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "the name after the account's prefix" }, "password": { "type": "string", "description": "empty: a random one is made" } }, "required": [ "name" ] }, "example": { "name": "example" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/database-users/{name}": { "get": { "operationId": "getDatabaseUser", "tags": [ "Databases" ], "summary": "One MySQL user", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "delete": { "operationId": "deleteDatabaseUser", "tags": [ "Databases" ], "summary": "Delete a MySQL user", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/subdomains": { "get": { "operationId": "listSubdomains", "tags": [ "Domains" ], "summary": "The account's subdomains", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" } }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Domain" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ { "domain": "example", "type": "example", "ssl": true, "ssl_expires": "example", "php": "example", "folder": "example", "target": "example" } ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "post": { "operationId": "createSubdomain", "tags": [ "Domains" ], "summary": "Add a subdomain under one of the account's main domains", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token. Send an Idempotency-Key header to retry safely.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "description": "the part before the main domain: letters, numbers and dashes (not \"www\")" }, "parent": { "type": "string", "description": "the main domain it belongs to" }, "folder": { "type": "string", "description": "the document folder inside web/ (default: its own)" } }, "required": [ "label", "parent" ] }, "example": { "label": "example", "parent": "example" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/Domain" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "domain": "blog.example.com", "folder": "web/blog.example.com/public_html", "php": "8.3", "ssl": false, "ssl_expires": null, "target": null, "type": "subdomain" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/subdomains/{subdomain}": { "get": { "operationId": "getSubdomain", "tags": [ "Domains" ], "summary": "One subdomain", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "subdomain", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/Domain" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "domain": "example", "type": "example", "ssl": true, "ssl_expires": "example", "php": "example", "folder": "example", "target": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "patch": { "operationId": "updateSubdomain", "tags": [ "Domains" ], "summary": "Set a subdomain's document folder or PHP version", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "subdomain", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "folder": { "type": "string", "description": "the document folder inside web/" }, "php": { "type": "string", "description": "an installed PHP version, e.g. 8.3" } } }, "example": { "folder": "example", "php": "example" } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/Domain" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "domain": "example", "type": "example", "ssl": true, "ssl_expires": "example", "php": "example", "folder": "example", "target": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true }, "delete": { "operationId": "deleteSubdomain", "tags": [ "Domains" ], "summary": "Remove a subdomain", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "subdomain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "purge", "in": "query", "required": false, "description": "also delete its files", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/redirects": { "get": { "operationId": "listRedirects", "tags": [ "Redirects" ], "summary": "The account's redirects and whole-site redirects", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "query", "required": false, "description": "only this website", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" } }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Redirect" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ { "id": 1, "domain": "example", "kind": "example", "path": "example", "target": "example", "code": 1 } ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "post": { "operationId": "createRedirect", "tags": [ "Redirects" ], "summary": "Redirect a path, or the whole website, to another address (a whole-site redirect replaces the earlier one)", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token. Send an Idempotency-Key header to retry safely.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "description": "the website" }, "kind": { "type": "string", "enum": [ "redirect", "whole" ], "description": "redirect (default) or whole" }, "path": { "type": "string", "description": "redirect: the path on the site, e.g. /old-page" }, "target": { "type": "string", "description": "redirect: a full address; whole: https://newsite.com" }, "code": { "type": "string", "enum": [ "301", "302" ], "description": "301 (default, permanent) or 302" } }, "required": [ "domain", "target" ] }, "example": { "domain": "example", "target": "example" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/Redirect" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "code": 301, "domain": "example.com", "id": 7, "kind": "redirect", "path": "/old", "target": "https://example.com/new" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/redirects/{id}": { "get": { "operationId": "getRedirect", "tags": [ "Redirects" ], "summary": "One redirect", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/Redirect" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "domain": "example", "kind": "example", "path": "example", "target": "example", "code": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "delete": { "operationId": "deleteRedirect", "tags": [ "Redirects" ], "summary": "Remove a redirect", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/ip-blocks": { "get": { "operationId": "listIpBlocks", "tags": [ "Firewall rules" ], "summary": "The addresses blocked on the account's websites (the IP blocker; older address of /ip-blocker)", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" } }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/AccountBlock" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ { "id": 1, "cidr": "example", "note": "example", "expires_at": "example", "created_at": "example" } ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "post": { "operationId": "createIpBlock", "tags": [ "Firewall rules" ], "summary": "Block an address or range on every website of the account (older address of /ip-blocker)", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token. Send an Idempotency-Key header to retry safely.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ip": { "type": "string", "description": "an address like 203.0.113.9 or a range like 203.0.113.0/24" } }, "required": [ "ip" ] }, "example": { "ip": "example" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/AccountBlock" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "cidr": "example", "note": "example", "expires_at": "example", "created_at": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/ip-blocks/{id}": { "delete": { "operationId": "deleteIpBlock", "tags": [ "Firewall rules" ], "summary": "Unblock an address of the IP blocker (older address of /ip-blocker/{id})", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/error-pages": { "get": { "operationId": "listErrorPageCodes", "tags": [ "Redirects" ], "summary": "The error codes a website can have its own page for, for each website of the account", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" } }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ErrorPage" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ { "domain": "example", "code": 1, "label": "example", "custom": true, "html": "example", "template": "example" } ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false } }, "/accounts/{username}/error-pages/{domain}/{code}": { "get": { "operationId": "getErrorPage", "tags": [ "Redirects" ], "summary": "A website's page for an error code: its HTML (when custom) and a template to start from", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/ErrorPage" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "domain": "example", "code": 1, "label": "example", "custom": true, "html": "example", "template": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "put": { "operationId": "setErrorPage", "tags": [ "Redirects" ], "summary": "Save a website's own page for an error code", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "html": { "type": "string", "description": "the page (up to 200,000 bytes)" } }, "required": [ "html" ] }, "example": { "html": "example" } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/ErrorPage" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "domain": "example", "code": 1, "label": "example", "custom": true, "html": "example", "template": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true }, "delete": { "operationId": "resetErrorPage", "tags": [ "Redirects" ], "summary": "Go back to the standard page for an error code", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/php": { "get": { "operationId": "getPhp", "tags": [ "PHP" ], "summary": "The account's PHP version, settings, extensions and websites", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/PhpSettings" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "version": "example", "versions": [], "settings": {}, "extensions": [], "sites": [] } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "patch": { "operationId": "updatePhp", "tags": [ "PHP" ], "summary": "Switch every website to another PHP version, and/or set the PHP settings of all websites", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "string", "description": "an available PHP version, e.g. 8.3" }, "settings": { "type": "object", "description": "memory_limit, upload_max_filesize, post_max_size (like 256M), max_execution_time, max_input_time (seconds), max_input_vars, display_errors, date.timezone; the ones you leave out go back to the defaults" } } }, "example": { "version": "example", "settings": {} } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/PhpSettings" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "version": "example", "versions": [], "settings": {}, "extensions": [], "sites": [] } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/php/sites": { "get": { "operationId": "listPhpSites", "tags": [ "PHP" ], "summary": "Each website's PHP version, web server mode and page cache", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" } }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PhpSite" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ { "domain": "example", "version": "example", "versions": [], "mode": "example", "page_cache": 1, "settings": {} } ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false } }, "/accounts/{username}/php/sites/{domain}": { "get": { "operationId": "getPhpSite", "tags": [ "PHP" ], "summary": "One website's PHP version, mode, page cache and its own PHP settings", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/PhpSite" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "domain": "example", "version": "example", "versions": [], "mode": "example", "page_cache": 1, "settings": {} } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "patch": { "operationId": "updatePhpSite", "tags": [ "PHP" ], "summary": "Set one website's PHP version, web server mode, page cache minutes and/or its own PHP settings (.user.ini)", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "string", "description": "an available PHP version" }, "mode": { "type": "string", "enum": [ "nginx", "hybrid" ], "description": "nginx (Nginx only, fastest) or hybrid (Nginx and Apache: .htaccess works)" }, "page_cache": { "type": "string", "enum": [ "0", "5", "10", "30", "60" ], "description": "minutes pages are kept: 0 (off), 5, 10, 30 or 60" }, "settings": { "type": "object", "description": "the settings to write into the website's .user.ini (same names as for the account)" } } }, "example": { "version": "example", "mode": "nginx", "page_cache": "0", "settings": {} } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/PhpSite" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "domain": "example", "version": "example", "versions": [], "mode": "example", "page_cache": 1, "settings": {} } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/php/sites/{domain}/cache/clear": { "post": { "operationId": "clearPhpSiteCache", "tags": [ "PHP" ], "summary": "Empty a website's page cache", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/tickets": { "get": { "operationId": "listTickets", "tags": [ "Tickets" ], "summary": "Support tickets (customers: their own; staff: those they may see), the ones waiting first. Up to 200 of the chosen kind.", "description": "Any token.", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "active (default: open and answered), closed or all", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" } }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Ticket" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ { "id": 1, "subject": "example", "status": "example", "priority": "example", "domain": "example", "account": "example", "email": "example", "updated_at": "example", "new": true, "tags": [], "notes": "example", "messages": [] } ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "any", "x-hf-write": false }, "post": { "operationId": "createTicket", "tags": [ "Tickets" ], "summary": "Open a ticket (customer tokens; up to 10 open at once)", "description": "Any token. Needs a \"Read & change\" token. Send an Idempotency-Key header to retry safely.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": "string", "description": "up to 150 characters" }, "body": { "type": "string", "description": "describe the problem" }, "priority": { "type": "string", "enum": [ "low", "normal", "high" ], "description": "normal by default" }, "domain": { "type": "string", "description": "one of the account's websites it is about" } }, "required": [ "subject", "body" ] }, "example": { "subject": "example", "body": "example" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/Ticket" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "subject": "example", "status": "example", "priority": "example", "domain": "example", "account": "example", "email": "example", "updated_at": "example", "new": true, "tags": [], "notes": "example", "messages": [] } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "any", "x-hf-write": true } }, "/tickets/{id}": { "get": { "operationId": "getTicket", "tags": [ "Tickets" ], "summary": "One ticket with its messages (marks it as read)", "description": "Any token.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/Ticket" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "subject": "example", "status": "example", "priority": "example", "domain": "example", "account": "example", "email": "example", "updated_at": "example", "new": true, "tags": [], "notes": "example", "messages": [] } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "any", "x-hf-write": false } }, "/tickets/{id}/reply": { "post": { "operationId": "replyTicket", "tags": [ "Tickets" ], "summary": "Add a message to a ticket", "description": "Any token. Needs a \"Read & change\" token.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "description": "the message" } }, "required": [ "body" ] }, "example": { "body": "example" } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/Ticket" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "subject": "example", "status": "example", "priority": "example", "domain": "example", "account": "example", "email": "example", "updated_at": "example", "new": true, "tags": [], "notes": "example", "messages": [] } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "any", "x-hf-write": true } }, "/tickets/{id}/close": { "post": { "operationId": "closeTicket", "tags": [ "Tickets" ], "summary": "Close a ticket", "description": "Any token. Needs a \"Read & change\" token.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/Ticket" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "subject": "example", "status": "example", "priority": "example", "domain": "example", "account": "example", "email": "example", "updated_at": "example", "new": true, "tags": [], "notes": "example", "messages": [] } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "any", "x-hf-write": true } }, "/tickets/{id}/reopen": { "post": { "operationId": "reopenTicket", "tags": [ "Tickets" ], "summary": "Open a closed ticket again", "description": "Any token. Needs a \"Read & change\" token.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/Ticket" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "subject": "example", "status": "example", "priority": "example", "domain": "example", "account": "example", "email": "example", "updated_at": "example", "new": true, "tags": [], "notes": "example", "messages": [] } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "any", "x-hf-write": true } }, "/webhook-events": { "get": { "operationId": "listWebhookEvents", "tags": [ "Webhooks" ], "summary": "Every event a webhook can get", "description": "Administrator tokens only.", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" } }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEvent" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ { "key": "example", "name": "example", "example": {} } ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": false } }, "/webhooks": { "get": { "operationId": "listWebhooks", "tags": [ "Webhooks" ], "summary": "The panel's webhooks", "description": "Administrator tokens only.", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" } }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ { "id": 1, "url": "example", "events": [], "enabled": true, "created_at": 1, "secret": "example" } ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": false }, "post": { "operationId": "createWebhook", "tags": [ "Webhooks" ], "summary": "Add a webhook (up to 20); the answer has its signing secret, once", "description": "Administrator tokens only. Needs a \"Read & change\" token. Send an Idempotency-Key header to retry safely.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "an https:// address" }, "events": { "type": "array", "items": { "type": "string" }, "description": "event keys from /webhook-events" }, "enabled": { "type": "boolean", "description": "on (default true)" } }, "required": [ "url", "events" ] }, "example": { "url": "example", "events": [ "example" ] } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/Webhook" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "url": "example", "events": [], "enabled": true, "created_at": 1, "secret": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": true } }, "/webhooks/{id}": { "get": { "operationId": "getWebhook", "tags": [ "Webhooks" ], "summary": "One webhook", "description": "Administrator tokens only.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/Webhook" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "url": "example", "events": [], "enabled": true, "created_at": 1, "secret": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": false }, "patch": { "operationId": "updateWebhook", "tags": [ "Webhooks" ], "summary": "Change a webhook's address, events or whether it is on", "description": "Administrator tokens only. Needs a \"Read & change\" token.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "an https:// address" }, "events": { "type": "array", "items": { "type": "string" }, "description": "event keys" }, "enabled": { "type": "boolean", "description": "on or off" } } }, "example": { "url": "example", "events": [ "example" ], "enabled": true } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/Webhook" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "url": "example", "events": [], "enabled": true, "created_at": 1, "secret": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": true }, "delete": { "operationId": "deleteWebhook", "tags": [ "Webhooks" ], "summary": "Delete a webhook and its deliveries", "description": "Administrator tokens only. Needs a \"Read & change\" token.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": true } }, "/webhooks/{id}/test": { "post": { "operationId": "testWebhook", "tags": [ "Webhooks" ], "summary": "Send a test event now and say how it went", "description": "Administrator tokens only. Needs a \"Read & change\" token.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": true } }, "/webhooks/{id}/regenerate-secret": { "post": { "operationId": "regenerateWebhookSecret", "tags": [ "Webhooks" ], "summary": "Make a new signing secret (the old one stops working); the answer has it, once", "description": "Administrator tokens only. Needs a \"Read & change\" token.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/Webhook" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "url": "example", "events": [], "enabled": true, "created_at": 1, "secret": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": true } }, "/notification-channels": { "get": { "operationId": "listNotificationChannels", "tags": [ "Notifications" ], "summary": "The token's login's notification channels", "description": "Any token.", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" } }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/NotificationChannel" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ { "id": 1, "kind": "example", "name": "example", "target": "example", "enabled": true, "last_test": "example", "last_test_ok": true, "secret": "example" } ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "any", "x-hf-write": false }, "post": { "operationId": "createNotificationChannel", "tags": [ "Notifications" ], "summary": "Add a channel; it gets the urgent events for now. A webhook channel's answer has its signing secret, once", "description": "Any token. Needs a \"Read & change\" token. Send an Idempotency-Key header to retry safely.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "description": "email, webhook, slack, discord, telegram or whatsapp (what the server allows)" }, "name": { "type": "string", "description": "a name" }, "to": { "type": "string", "description": "email: the address" }, "url": { "type": "string", "description": "webhook, slack, discord: the address" }, "token": { "type": "string", "description": "telegram: the bot token" }, "chat": { "type": "string", "description": "telegram: the chat id or @channel" }, "wa_phone_id": { "type": "string", "description": "whatsapp: the business phone number ID" }, "wa_to": { "type": "string", "description": "whatsapp: the number that gets the alerts" }, "wa_template": { "type": "string", "description": "whatsapp: an approved template's name (optional)" }, "wa_lang": { "type": "string", "description": "whatsapp: the template's language (default en)" } }, "required": [ "kind" ] }, "example": { "kind": "example" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/NotificationChannel" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "kind": "example", "name": "example", "target": "example", "enabled": true, "last_test": "example", "last_test_ok": true, "secret": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "any", "x-hf-write": true } }, "/notification-channels/{id}": { "get": { "operationId": "getNotificationChannel", "tags": [ "Notifications" ], "summary": "One channel", "description": "Any token.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/NotificationChannel" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "kind": "example", "name": "example", "target": "example", "enabled": true, "last_test": "example", "last_test_ok": true, "secret": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "any", "x-hf-write": false }, "patch": { "operationId": "updateNotificationChannel", "tags": [ "Notifications" ], "summary": "Pause or resume a channel", "description": "Any token. Needs a \"Read & change\" token.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "on or paused" } }, "required": [ "enabled" ] }, "example": { "enabled": true } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/NotificationChannel" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "kind": "example", "name": "example", "target": "example", "enabled": true, "last_test": "example", "last_test_ok": true, "secret": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "any", "x-hf-write": true }, "delete": { "operationId": "deleteNotificationChannel", "tags": [ "Notifications" ], "summary": "Remove a channel and its subscriptions", "description": "Any token. Needs a \"Read & change\" token.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "any", "x-hf-write": true } }, "/notification-channels/{id}/test": { "post": { "operationId": "testNotificationChannel", "tags": [ "Notifications" ], "summary": "Send a test message (5 in 10 minutes)", "description": "Any token. Needs a \"Read & change\" token.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "any", "x-hf-write": true } }, "/notification-channels/{id}/rotate-secret": { "post": { "operationId": "rotateNotificationSecret", "tags": [ "Notifications" ], "summary": "Webhook channels: make a new signing secret; the answer has it, once", "description": "Any token. Needs a \"Read & change\" token.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/NotificationChannel" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "id": 1, "kind": "example", "name": "example", "target": "example", "enabled": true, "last_test": "example", "last_test_ok": true, "secret": "example" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "any", "x-hf-write": true } }, "/notification-subscriptions": { "get": { "operationId": "listNotificationSubscriptions", "tags": [ "Notifications" ], "summary": "Which events go to which channel", "description": "Any token.", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" } }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/NotificationSubscription" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ { "event": "example", "channel_id": 1 } ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "any", "x-hf-write": false }, "put": { "operationId": "setNotificationSubscriptions", "tags": [ "Notifications" ], "summary": "Replace the subscriptions with this list (unknown events and other people's channels are left out)", "description": "Any token. Needs a \"Read & change\" token.", "parameters": [ { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subscriptions": { "type": "array", "items": { "type": "string" }, "description": "objects with event and channel_id" } }, "required": [ "subscriptions" ] }, "example": { "subscriptions": [ "example" ] } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/NotificationSubscription" } }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "event": "example", "channel_id": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "any", "x-hf-write": true } }, "/notification-quiet-hours": { "get": { "operationId": "getNotificationQuietHours", "tags": [ "Notifications" ], "summary": "The quiet hours", "description": "Any token.", "parameters": [ { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/NotificationQuietHours" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "on": true, "from": "example", "to": "example", "tz": "example", "urgent": true } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "any", "x-hf-write": false }, "put": { "operationId": "setNotificationQuietHours", "tags": [ "Notifications" ], "summary": "Save the quiet hours", "description": "Any token. Needs a \"Read & change\" token.", "parameters": [ { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "on": { "type": "boolean", "description": "quiet hours on" }, "from": { "type": "string", "description": "HH:MM" }, "to": { "type": "string", "description": "HH:MM" }, "tz": { "type": "string", "description": "a time zone name (default UTC)" }, "urgent": { "type": "boolean", "description": "urgent events still come through" } }, "required": [ "on", "from", "to" ] }, "example": { "on": true, "from": "example", "to": "example" } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/NotificationQuietHours" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": { "on": true, "from": "example", "to": "example", "tz": "example", "urgent": true } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "any", "x-hf-write": true } }, "/notification-events": { "get": { "operationId": "listNotificationEvents", "tags": [ "Notifications" ], "summary": "The events this login's role can subscribe to", "description": "Any token.", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" } }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/NotificationEvent" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ { "key": "example", "name": "example", "description": "example", "group": "example", "urgent": true } ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "any", "x-hf-write": false } }, "/notification-deliveries": { "get": { "operationId": "listNotificationDeliveries", "tags": [ "Notifications" ], "summary": "The last 50 notifications", "description": "Any token.", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" } }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/NotificationDelivery" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ { "id": 1, "when": "example", "event": "example", "title": "example", "channel": "example", "status": "example", "attempts": 1, "error": "example", "test": true } ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "any", "x-hf-write": false } }, "/search": { "get": { "operationId": "search", "tags": [ "Accounts" ], "summary": "Search accounts, domains, mailboxes, databases, invoices, tickets, resellers, IP addresses and screens (staff: what they may see)", "description": "Administrator and reseller tokens.", "parameters": [ { "name": "q", "in": "query", "required": true, "description": "what to look for (at least 2 characters)", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "hits per group, 1–20 (default 5)", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "staff", "x-hf-write": false } }, "/accounts/{username}/firewall-rules": { "get": { "operationId": "listFirewallRules", "tags": [ "Firewall rules" ], "summary": "Every website of the account with its firewall rules", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "which page, from 1 (a list is paged by default on the REST resources; the older lists answer everything until a page is asked for)", "schema": { "type": "integer" }, "x-hf-generic": true }, { "name": "per_page", "in": "query", "required": false, "description": "items per page, 1–200 (default 50 on the REST resources)", "schema": { "type": "integer" }, "x-hf-generic": true }, { "name": "q", "in": "query", "required": false, "description": "only items with these words in any value", "schema": { "type": "string" }, "x-hf-generic": true }, { "name": "status", "in": "query", "required": false, "description": "only items with this status", "schema": { "type": "string" }, "x-hf-generic": true }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "type": "object" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "ok": true, "data": [ {} ], "meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false } }, "/accounts/{username}/firewall-rules/{domain}": { "get": { "operationId": "getFirewallRules", "tags": [ "Firewall rules" ], "summary": "A website's firewall rules", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false }, "put": { "operationId": "setFirewallRules", "tags": [ "Firewall rules" ], "summary": "Set a website's firewall rules (tested by the web server before they apply)", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "allow": { "type": "array", "items": { "type": "string" }, "description": "allowed IP addresses or ranges (they skip every other rule)" }, "block": { "type": "array", "items": { "type": "string" }, "description": "blocked IP addresses or ranges" }, "only_allowed": { "type": "boolean", "description": "only the allowed addresses may open the website" }, "countries": { "type": "array", "items": { "type": "string" }, "description": "blocked countries, two-letter codes (needs the country list)" }, "login_limit": { "type": "boolean", "description": "limit requests to login pages" }, "rate": { "type": "integer", "enum": [ "5", "10", "20", "60" ], "description": "login requests per minute and visitor" }, "paths": { "type": "array", "items": { "type": "string" }, "description": "the limited paths, e.g. /wp-login.php (a path also covers what starts with it)" }, "bot": { "type": "string", "enum": [ "off", "suspicious", "all" ], "description": "bot protection: off, suspicious (empty or tool-like user agents) or all visitors" }, "crawlers": { "type": "boolean", "description": "let known search engine crawlers through" }, "verify_crawlers": { "type": "boolean", "description": "only after checking their reverse DNS" } } }, "example": { "allow": [ "example" ], "block": [ "example" ], "only_allowed": true, "countries": [ "example" ] } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true }, "post": { "operationId": "setFirewallRulesPost", "tags": [ "Firewall rules" ], "summary": "Set a website's firewall rules (tested by the web server before they apply)", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "allow": { "type": "array", "items": { "type": "string" }, "description": "allowed IP addresses or ranges (they skip every other rule)" }, "block": { "type": "array", "items": { "type": "string" }, "description": "blocked IP addresses or ranges" }, "only_allowed": { "type": "boolean", "description": "only the allowed addresses may open the website" }, "countries": { "type": "array", "items": { "type": "string" }, "description": "blocked countries, two-letter codes (needs the country list)" }, "login_limit": { "type": "boolean", "description": "limit requests to login pages" }, "rate": { "type": "integer", "enum": [ "5", "10", "20", "60" ], "description": "login requests per minute and visitor" }, "paths": { "type": "array", "items": { "type": "string" }, "description": "the limited paths, e.g. /wp-login.php (a path also covers what starts with it)" }, "bot": { "type": "string", "enum": [ "off", "suspicious", "all" ], "description": "bot protection: off, suspicious (empty or tool-like user agents) or all visitors" }, "crawlers": { "type": "boolean", "description": "let known search engine crawlers through" }, "verify_crawlers": { "type": "boolean", "description": "only after checking their reverse DNS" } } }, "example": { "allow": [ "example" ], "block": [ "example" ], "only_allowed": true, "countries": [ "example" ] } } } }, "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true }, "delete": { "operationId": "clearFirewallRules", "tags": [ "Firewall rules" ], "summary": "Switch every firewall rule of a website off", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/accounts/{username}/firewall-rules/{domain}/log": { "get": { "operationId": "getFirewallLog", "tags": [ "Firewall rules" ], "summary": "Refused requests of a website: a summary and the newest 50", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false } }, "/accounts/{username}/cron-jobs/{id}/runs": { "get": { "operationId": "getCronJobRuns", "tags": [ "Cron jobs" ], "summary": "A cron job's monitor state and its last 50 runs (exit code, duration, output)", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false } }, "/accounts/{username}/cron-jobs/{id}/run": { "post": { "operationId": "runCronJob", "tags": [ "Cron jobs" ], "summary": "Run a cron job now as the account (2 minutes at most)", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage. Needs a \"Read & change\" token.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": true } }, "/server/capacity": { "get": { "operationId": "getCapacityForecast", "tags": [ "Server" ], "summary": "When disk space, files and memory are expected to run out, and the accounts growing fastest", "description": "Administrator tokens only.", "parameters": [ { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "admin", "x-hf-write": false } }, "/accounts/{username}/domains/{domain}/stats": { "get": { "operationId": "getSiteStats", "tags": [ "Domains" ], "summary": "A website's visitor statistics from its access logs (no addresses stored): totals, days, the last 48 hours and top lists", "description": "Per account: a customer's token works on its own account only; administrator and reseller tokens on any account they manage.", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "first day, YYYY-MM-DD (with to; at most 13 months back)", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "description": "last day, YYYY-MM-DD", "schema": { "type": "string" } }, { "name": "days", "in": "query", "required": false, "description": "the last days instead of from/to (default 30)", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ErrorFormat" } ], "responses": { "200": { "description": "Done", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "example": { "ok": true, "data": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-hf-who": "account", "x-hf-write": false } }, "/licence/partner/licences": { "get": { "operationId": "partnerLicences", "tags": [ "Partner licences" ], "summary": "Your pool and every licence", "description": "Only on the publisher's licence server. A partner API key (made in HQ › Partners): Authorization: Bearer hfp_…. Answers plain JSON (not {\"ok\", \"data\"}); a refusal is {\"error\": \"…\"}.", "security": [ { "partner": [] } ], "responses": { "200": { "description": "Done", "content": { "application/json": { "schema": { "type": "object", "properties": { "quantity": { "type": "integer" }, "used": { "type": "integer" }, "licences": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "email": { "type": "string" }, "ip": { "type": "string" }, "status": { "type": "string", "description": "the licence's status: active, past_due, grace, expired, cancelled, revoked …" }, "products": { "type": "array", "description": "the licence's product lines, each with its plan (limit 0 = unlimited)", "items": { "type": "object", "properties": { "product": { "type": "string", "enum": [ "panel", "cloud", "deploy" ] }, "name": { "type": "string" }, "plan": { "type": "string" }, "plan_name": { "type": "string" }, "limit": { "type": "integer", "description": "KVM hosts (HF Cloud) or apps (HF Deploy); 0 = unlimited" }, "unit": { "type": "string" } } } }, "install": { "type": "string", "description": "the install command with the key in it" } } } } } }, "example": { "quantity": 50, "used": 1, "licences": [ { "key": "HFL-ABCD-EFGH-JKLM-NPQR-STUV", "email": "customer@example.com", "ip": "203.0.113.10", "status": "active", "products": [ { "product": "panel", "name": "HF Panel", "plan": "pro", "plan_name": "Pro" }, { "product": "deploy", "name": "HF Deploy", "plan": "deploy-starter", "plan_name": "Starter", "limit": 10, "unit": "apps" } ], "install": "bash <(curl -fsSL https://cdn.yourdomain.com/latest/licence/HFL-…)" } ] } } } }, "401": { "description": "No valid partner API key", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "The partner's bulk licences are not active", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "405": { "description": "The wrong method", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Refused (pool full, server already licensed, not a public IPv4 address; an atomic bulk call with a refused item)", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "A malformed body or query, or an Idempotency-Key used for another request", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many calls", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "x-hf-who": "partner", "x-hf-write": false, "servers": [ { "url": "https://api.yourdomain.com/v1", "description": "The API's own address" } ] } }, "/licence/partner/fleet": { "get": { "operationId": "partnerFleet", "tags": [ "Partner licences" ], "summary": "Every licence with its server's state (paged)", "description": "Only on the publisher's licence server. A partner API key (made in HQ › Partners): Authorization: Bearer hfp_…. Answers plain JSON (not {\"ok\", \"data\"}); a refusal is {\"error\": \"…\"}.", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "which page, from 1", "schema": { "type": "integer", "description": "which page, from 1" } }, { "name": "per", "in": "query", "required": false, "description": "licences per page, 1–500 (default 100)", "schema": { "type": "integer", "description": "licences per page, 1–500 (default 100)" } }, { "name": "status", "in": "query", "required": false, "description": "only licences with this fleet status", "schema": { "type": "string", "enum": [ "active", "new", "unseen", "suspended" ], "description": "only licences with this fleet status" } }, { "name": "version", "in": "query", "required": false, "description": "only servers that reported this HF Panel version", "schema": { "type": "string", "description": "only servers that reported this HF Panel version" } } ], "security": [ { "partner": [] } ], "responses": { "200": { "description": "Done", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer" }, "page": { "type": "integer" }, "per": { "type": "integer" }, "pages": { "type": "integer" }, "counts": { "type": "object", "description": "every licence by fleet status, before the filters", "properties": { "active": { "type": "integer" }, "new": { "type": "integer" }, "unseen": { "type": "integer" }, "suspended": { "type": "integer" } } }, "licences": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "email": { "type": "string" }, "ip": { "type": "string" }, "hostname": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "new", "unseen", "suspended" ], "description": "active: checked in within 7 days; new: not checked in yet (issued less than 7 days ago); unseen: no check-in for 7 days or more; suspended: the licence does not work" }, "licence_status": { "type": "string", "description": "the licence's own status (active, past_due, grace, expired, cancelled, revoked …)" }, "last_check_at": { "type": [ "string", "null" ], "description": "the last licence check (RFC 3339, UTC)" }, "last_check_ip": { "type": "string" }, "version": { "type": "string", "description": "the HF Panel version the server reported" }, "accounts": { "type": [ "integer", "null" ], "description": "hosting accounts the server reported; null until it first checks in" }, "plan": { "type": "string", "description": "the plan's key ('' = none)" }, "tier": { "type": "string" }, "features": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "the feature keys; null = every feature" }, "products": { "type": "array", "description": "the licence's product lines, each with its plan (limit 0 = unlimited)", "items": { "type": "object", "properties": { "product": { "type": "string", "enum": [ "panel", "cloud", "deploy" ] }, "name": { "type": "string" }, "plan": { "type": "string" }, "plan_name": { "type": "string" }, "limit": { "type": "integer", "description": "KVM hosts (HF Cloud) or apps (HF Deploy); 0 = unlimited" }, "unit": { "type": "string" } } } }, "created_at": { "type": [ "string", "null" ] } } } } } }, "example": { "total": 1, "page": 1, "per": 100, "pages": 1, "counts": { "active": 1, "new": 0, "unseen": 0, "suspended": 0 }, "licences": [ { "key": "HFL-ABCD-EFGH-JKLM-NPQR-STUV", "email": "customer@example.com", "ip": "203.0.113.10", "hostname": "srv1.example.com", "status": "active", "licence_status": "active", "last_check_at": "2026-11-02T05:47:00Z", "last_check_ip": "203.0.113.10", "version": "1.0.0", "accounts": 42, "plan": "", "tier": "pro", "features": null, "products": [ { "product": "panel", "name": "HF Panel", "plan": "pro", "plan_name": "Pro" }, { "product": "deploy", "name": "HF Deploy", "plan": "deploy-starter", "plan_name": "Starter", "limit": 10, "unit": "apps" } ], "created_at": "2026-10-01T09:00:00Z" } ] } } } }, "401": { "description": "No valid partner API key", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "The partner's bulk licences are not active", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "405": { "description": "The wrong method", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Refused (pool full, server already licensed, not a public IPv4 address; an atomic bulk call with a refused item)", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "A malformed body or query, or an Idempotency-Key used for another request", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many calls", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "x-hf-who": "partner", "x-hf-write": false, "servers": [ { "url": "https://api.yourdomain.com/v1", "description": "The API's own address" } ] } }, "/licence/partner/issue": { "post": { "operationId": "partnerIssue", "tags": [ "Partner licences" ], "summary": "Issue a licence for a server", "description": "Only on the publisher's licence server. A partner API key (made in HQ › Partners): Authorization: Bearer hfp_…. Answers plain JSON (not {\"ok\", \"data\"}); a refusal is {\"error\": \"…\"}.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "the customer's email" }, "ip": { "type": "string", "description": "the server's public IPv4 address" }, "products": { "type": "object", "description": "the product lines and plans: {\"panel\": an HF Panel plan key or \"none\", \"cloud\": an HF Cloud plan key (the publisher's own plans) or \"\", \"deploy\": an HF Deploy plan key or \"\"}; issued without it, a licence has every HF Panel feature (HF Cloud and HF Deploy only as their own lines)" } }, "required": [ "email", "ip" ] } } } }, "security": [ { "partner": [] } ], "responses": { "200": { "description": "Done", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string" }, "products": { "type": "array", "description": "the licence's product lines, each with its plan (limit 0 = unlimited)", "items": { "type": "object", "properties": { "product": { "type": "string", "enum": [ "panel", "cloud", "deploy" ] }, "name": { "type": "string" }, "plan": { "type": "string" }, "plan_name": { "type": "string" }, "limit": { "type": "integer", "description": "KVM hosts (HF Cloud) or apps (HF Deploy); 0 = unlimited" }, "unit": { "type": "string" } } } }, "install": { "type": "string" } } }, "example": { "key": "HFL-ABCD-EFGH-JKLM-NPQR-STUV", "products": [ { "product": "panel", "name": "HF Panel", "plan": "pro", "plan_name": "Pro" }, { "product": "deploy", "name": "HF Deploy", "plan": "deploy-starter", "plan_name": "Starter", "limit": 10, "unit": "apps" } ], "install": "bash <(curl -fsSL https://cdn.yourdomain.com/latest/licence/HFL-…)" } } } }, "400": { "description": "A malformed Idempotency-Key", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "No valid partner API key", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "The partner's bulk licences are not active", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "No such licence among the partner's", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "405": { "description": "The wrong method", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Refused (pool full, server already licensed, not a public IPv4 address; an atomic bulk call with a refused item)", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "A malformed body or query, or an Idempotency-Key used for another request", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many calls", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "x-hf-who": "partner", "x-hf-write": true, "servers": [ { "url": "https://api.yourdomain.com/v1", "description": "The API's own address" } ] } }, "/licence/partner/products": { "post": { "operationId": "partnerProducts", "tags": [ "Partner licences" ], "summary": "Change a licence's product lines and plans", "description": "Only on the publisher's licence server. A partner API key (made in HQ › Partners): Authorization: Bearer hfp_…. Answers plain JSON (not {\"ok\", \"data\"}); a refusal is {\"error\": \"…\"}.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "description": "the licence key" }, "products": { "type": "object", "description": "the product lines and plans: {\"panel\": an HF Panel plan key or \"none\", \"cloud\": an HF Cloud plan key (the publisher's own plans) or \"\", \"deploy\": an HF Deploy plan key or \"\"}; issued without it, a licence has every HF Panel feature (HF Cloud and HF Deploy only as their own lines)" } }, "required": [ "key", "products" ] } } } }, "security": [ { "partner": [] } ], "responses": { "200": { "description": "Done", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string" }, "products": { "type": "array", "description": "the licence's product lines, each with its plan (limit 0 = unlimited)", "items": { "type": "object", "properties": { "product": { "type": "string", "enum": [ "panel", "cloud", "deploy" ] }, "name": { "type": "string" }, "plan": { "type": "string" }, "plan_name": { "type": "string" }, "limit": { "type": "integer", "description": "KVM hosts (HF Cloud) or apps (HF Deploy); 0 = unlimited" }, "unit": { "type": "string" } } } } } }, "example": { "key": "HFL-ABCD-EFGH-JKLM-NPQR-STUV", "products": [ { "product": "panel", "name": "HF Panel", "plan": "pro", "plan_name": "Pro" }, { "product": "deploy", "name": "HF Deploy", "plan": "deploy-starter", "plan_name": "Starter", "limit": 10, "unit": "apps" } ] } } } }, "400": { "description": "A malformed Idempotency-Key", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "No valid partner API key", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "The partner's bulk licences are not active", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "No such licence among the partner's", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "405": { "description": "The wrong method", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Refused (pool full, server already licensed, not a public IPv4 address; an atomic bulk call with a refused item)", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "A malformed body or query, or an Idempotency-Key used for another request", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many calls", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "x-hf-who": "partner", "x-hf-write": true, "servers": [ { "url": "https://api.yourdomain.com/v1", "description": "The API's own address" } ] } }, "/licence/partner/issue-bulk": { "post": { "operationId": "partnerIssueBulk", "tags": [ "Partner licences" ], "summary": "Issue up to 500 licences", "description": "Only on the publisher's licence server. A partner API key (made in HQ › Partners): Authorization: Bearer hfp_…. Answers plain JSON (not {\"ok\", \"data\"}); a refusal is {\"error\": \"…\"}.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "servers": { "type": "array", "maxItems": 500, "description": "up to 500 {email, ip, products} objects", "items": { "type": "object", "required": [ "email", "ip" ], "properties": { "email": { "type": "string" }, "ip": { "type": "string" }, "products": { "type": "object", "description": "the product lines and plans: {\"panel\": an HF Panel plan key or \"none\", \"cloud\": an HF Cloud plan key (the publisher's own plans) or \"\", \"deploy\": an HF Deploy plan key or \"\"}; issued without it, a licence has every HF Panel feature (HF Cloud and HF Deploy only as their own lines)" } } } }, "atomic": { "type": "boolean", "description": "all or nothing: the pool must have room for all, and nothing is issued when any item is refused (409)" } }, "required": [ "servers" ] } } } }, "security": [ { "partner": [] } ], "responses": { "200": { "description": "Done", "content": { "application/json": { "schema": { "type": "object", "properties": { "issued": { "type": "integer" }, "failed": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "email": { "type": "string" }, "ip": { "type": "string" }, "key": { "type": "string" }, "install": { "type": "string" }, "error": { "type": "string", "description": "why this item was refused" } } }, "description": "one per item, in order" } } }, "example": { "issued": 1, "failed": 1, "results": [ { "index": 0, "email": "one@example.com", "ip": "203.0.113.31", "key": "HFL-ABCD-EFGH-JKLM-NPQR-STUV", "install": "bash <(curl -fsSL …)" }, { "index": 1, "email": "two@example.com", "ip": "203.0.113.31", "error": "That server already has a licence." } ] } } } }, "400": { "description": "A malformed Idempotency-Key", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "No valid partner API key", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "The partner's bulk licences are not active", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "No such licence among the partner's", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "405": { "description": "The wrong method", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Refused (pool full, server already licensed, not a public IPv4 address; an atomic bulk call with a refused item)", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "A malformed body or query, or an Idempotency-Key used for another request", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many calls", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "x-hf-who": "partner", "x-hf-write": true, "servers": [ { "url": "https://api.yourdomain.com/v1", "description": "The API's own address" } ] } }, "/licence/partner/move": { "post": { "operationId": "partnerMove", "tags": [ "Partner licences" ], "summary": "Move a licence to another server", "description": "Only on the publisher's licence server. A partner API key (made in HQ › Partners): Authorization: Bearer hfp_…. Answers plain JSON (not {\"ok\", \"data\"}); a refusal is {\"error\": \"…\"}.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "description": "the licence key" }, "ip": { "type": "string", "description": "the new server's public IPv4 address" } }, "required": [ "key", "ip" ] } } } }, "security": [ { "partner": [] } ], "responses": { "200": { "description": "Done", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string" }, "ip": { "type": "string" } } }, "example": { "key": "HFL-ABCD-EFGH-JKLM-NPQR-STUV", "ip": "203.0.113.20" } } } }, "400": { "description": "A malformed Idempotency-Key", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "No valid partner API key", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "The partner's bulk licences are not active", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "No such licence among the partner's", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "405": { "description": "The wrong method", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Refused (pool full, server already licensed, not a public IPv4 address; an atomic bulk call with a refused item)", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "A malformed body or query, or an Idempotency-Key used for another request", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many calls", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "x-hf-who": "partner", "x-hf-write": true, "servers": [ { "url": "https://api.yourdomain.com/v1", "description": "The API's own address" } ] } }, "/licence/partner/remove": { "post": { "operationId": "partnerRemove", "tags": [ "Partner licences" ], "summary": "Remove a licence (frees its place in the pool)", "description": "Only on the publisher's licence server. A partner API key (made in HQ › Partners): Authorization: Bearer hfp_…. Answers plain JSON (not {\"ok\", \"data\"}); a refusal is {\"error\": \"…\"}.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "description": "the licence key" } }, "required": [ "key" ] } } } }, "security": [ { "partner": [] } ], "responses": { "200": { "description": "Done", "content": { "application/json": { "schema": { "type": "object", "properties": { "removed": { "type": "string" } } }, "example": { "removed": "HFL-ABCD-EFGH-JKLM-NPQR-STUV" } } } }, "400": { "description": "A malformed Idempotency-Key", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "No valid partner API key", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "The partner's bulk licences are not active", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "No such licence among the partner's", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "405": { "description": "The wrong method", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Refused (pool full, server already licensed, not a public IPv4 address; an atomic bulk call with a refused item)", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "A malformed body or query, or an Idempotency-Key used for another request", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many calls", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "x-hf-who": "partner", "x-hf-write": true, "servers": [ { "url": "https://api.yourdomain.com/v1", "description": "The API's own address" } ] } }, "/licence/partner/remove-bulk": { "post": { "operationId": "partnerRemoveBulk", "tags": [ "Partner licences" ], "summary": "Remove up to 500 licences", "description": "Only on the publisher's licence server. A partner API key (made in HQ › Partners): Authorization: Bearer hfp_…. Answers plain JSON (not {\"ok\", \"data\"}); a refusal is {\"error\": \"…\"}.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "keys": { "type": "array", "maxItems": 500, "description": "up to 500 licence keys", "items": { "type": "string" } }, "atomic": { "type": "boolean", "description": "all or nothing: nothing is removed when any key is refused (409)" } }, "required": [ "keys" ] } } } }, "security": [ { "partner": [] } ], "responses": { "200": { "description": "Done", "content": { "application/json": { "schema": { "type": "object", "properties": { "removed": { "type": "integer" }, "failed": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "key": { "type": "string" }, "removed": { "type": "boolean" }, "error": { "type": "string", "description": "why this item was refused" } } }, "description": "one per item, in order" } } }, "example": { "removed": 1, "failed": 0, "results": [ { "index": 0, "key": "HFL-ABCD-EFGH-JKLM-NPQR-STUV", "removed": true } ] } } } }, "400": { "description": "A malformed Idempotency-Key", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "No valid partner API key", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "The partner's bulk licences are not active", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "No such licence among the partner's", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "405": { "description": "The wrong method", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Refused (pool full, server already licensed, not a public IPv4 address; an atomic bulk call with a refused item)", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "A malformed body or query, or an Idempotency-Key used for another request", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many calls", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "x-hf-who": "partner", "x-hf-write": true, "servers": [ { "url": "https://api.yourdomain.com/v1", "description": "The API's own address" } ] } } }, "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "bearerFormat": "hf_ followed by 48 hexadecimal characters", "description": "An API token made under Password & security › API tokens" }, "partner": { "type": "http", "scheme": "bearer", "bearerFormat": "hfp_ followed by 48 hexadecimal characters", "description": "A partner API key made in HQ › Partners on the publisher's licence server (the Partner licences operations only)" } }, "parameters": { "ErrorFormat": { "name": "X-HF-Errors", "in": "header", "required": false, "description": "object: errors are {\"code\", \"message\"} objects instead of a sentence (or add ?errors=object)", "schema": { "type": "string", "enum": [ "object" ] } }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Up to 255 printable characters. The same key with the same request within 24 hours gives the first answer again instead of doing it twice.", "schema": { "type": "string", "maxLength": 255 } } }, "headers": { "Location": { "description": "the new item's address, relative to the server (201 answers)", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "requests this token may make per minute", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "requests left in this minute", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "when the minute ends (Unix time, seconds)", "schema": { "type": "integer" } } }, "responses": { "Error": { "description": "Refused; error says why", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Error": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "const": false }, "error": { "description": "a plain sentence you can show to a person; or, when the request sends X-HF-Errors: object (or the server is set to), the standard object", "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/ErrorObject" } ] } }, "example": { "ok": false, "error": "No such account." } }, "ErrorObject": { "type": "object", "description": "The standard error: a stable code, a sentence for a person, and for a form check the field it is about", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "licence_required", "forbidden", "not_found", "conflict", "validation_failed", "rate_limited", "upstream_error", "server_error" ], "description": "400 bad_request, 401 unauthorized, 402 licence_required, 403 forbidden, 404 not_found, 409 conflict, 422 validation_failed, 429 rate_limited, 502 upstream_error, 500 server_error" }, "message": { "type": "string" }, "field": { "type": "string", "description": "the body field or query parameter the message is about" }, "fields": { "type": "object", "description": "several fields at once: name to message" } }, "example": { "code": "not_found", "message": "No such account." } }, "ListMeta": { "type": "object", "description": "The totals of a list answer", "properties": { "total": { "type": "integer", "description": "items in all (after ?q= and ?status=)" }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total_pages": { "type": "integer" } }, "example": { "total": 120, "page": 1, "per_page": 50, "total_pages": 3 } }, "Me": { "type": "object", "description": "Who the token belongs to", "properties": { "username": { "type": "string", "description": "the login" }, "email": { "type": "string", "description": "its email" }, "role": { "type": "string", "description": "admin, reseller or client" }, "two_factor": { "type": "boolean", "description": "two-factor login is on" }, "token": { "type": "object", "description": "name and access (read or write)" } } }, "Package": { "type": "object", "description": "A hosting package", "properties": { "id": { "type": "integer", "description": "its id" }, "name": { "type": "string", "description": "its name" }, "disk_mb": { "type": "integer", "description": "disk space in MB" }, "max_domains": { "type": "integer", "description": "0 = no limit" }, "max_databases": { "type": "integer", "description": "MySQL and PostgreSQL; 0 = no limit" }, "max_mongo_databases": { "type": "integer", "description": "MongoDB" }, "max_mailboxes": { "type": "integer", "description": "0 = no limit" }, "price_month": { "type": "number", "description": "monthly price" }, "redis_mb": { "type": "integer", "description": "Redis memory in MB (0 = none)" }, "memcached_mb": { "type": "integer", "description": "Memcached memory in MB (0 = none)" } } }, "Account": { "type": "object", "description": "A hosting account", "properties": { "username": { "type": "string", "description": "its username" }, "email": { "type": "string", "description": "contact email" }, "status": { "type": "string", "description": "active or suspended" }, "package": { "type": [ "string", "null" ], "description": "the package's name" }, "disk_used_mb": { "type": "integer", "description": "disk used" }, "disk_limit_mb": { "type": "integer", "description": "disk allowed" }, "domains": { "type": "array", "items": { "type": "string" }, "description": "every domain" }, "two_factor": { "type": "boolean", "description": "two-factor login is on" }, "server": { "type": "string", "description": "the server it lives on" }, "created_at": { "type": "string", "description": "UTC" }, "last_login_at": { "type": [ "string", "null" ], "description": "UTC" } } }, "AccountUsage": { "type": "object", "description": "An account's usage: counts, disk, bandwidth and its resources against the limits", "properties": { "username": { "type": "string", "description": "its username" }, "disk_used_mb": { "type": "integer", "description": "disk used" }, "disk_limit_mb": { "type": "integer", "description": "disk allowed (0 = no limit)" }, "bandwidth_month_mb": { "type": "integer", "description": "this month" }, "domains": { "type": "integer", "description": "domains" }, "mailboxes": { "type": "integer", "description": "mailboxes" }, "databases": { "type": "integer", "description": "MySQL and PostgreSQL" }, "mongo_databases": { "type": "integer", "description": "MongoDB" }, "resources": { "type": "object", "description": "period, supported (the server measures: cgroup v2), enforced, limits {cpu_percent (100 = one core), memory_mb, processes, io_mbps, iops, php_workers, app_processes, disk_mb; 0 = no limit}, now (the newest minute or null), limit_hits_24h and series {time (Unix), cpu_percent, memory_mb, processes, io_read_mbps, io_write_mbps, iops, disk_mb}" } } }, "Reseller": { "type": "object", "description": "A reseller", "properties": { "username": { "type": "string", "description": "the login" }, "email": { "type": "string", "description": "contact email" }, "status": { "type": "string", "description": "active or suspended" }, "max_accounts": { "type": "integer", "description": "0 = no limit" }, "accounts": { "type": "integer", "description": "their customers" }, "approval": { "type": "string", "description": "default, on or off: whether their deletes wait for approval" }, "created_at": { "type": "string", "description": "UTC" } } }, "Domain": { "type": "object", "description": "A domain", "properties": { "domain": { "type": "string", "description": "the name" }, "type": { "type": "string", "description": "website, subdomain or parked" }, "ssl": { "type": "boolean", "description": "has a certificate" }, "ssl_expires": { "type": [ "string", "null" ], "description": "when it ends" }, "php": { "type": [ "string", "null" ], "description": "PHP version" }, "folder": { "type": [ "string", "null" ], "description": "document folder (web/…)" }, "target": { "type": [ "string", "null" ], "description": "parked: the website it shows" } } }, "DnsRecord": { "type": "object", "description": "A DNS record", "properties": { "id": { "type": "integer", "description": "its id" }, "name": { "type": "string", "description": "@ or the part before the zone" }, "type": { "type": "string", "description": "A, AAAA, CNAME, ALIAS, MX, TXT, SRV, CAA or NS" }, "value": { "type": "string", "description": "the value" }, "ttl": { "type": "integer", "description": "seconds" }, "priority": { "type": "integer", "description": "MX and SRV" } } }, "DnsZone": { "type": "object", "description": "A DNS zone", "properties": { "domain": { "type": "string" }, "dnssec": { "type": "boolean" }, "records": { "description": "the records (one zone), or how many (the list of zones)", "oneOf": [ { "type": "integer" }, { "type": "array", "items": { "$ref": "#/components/schemas/DnsRecord" } } ] } } }, "Mailbox": { "type": "object", "description": "A mailbox", "properties": { "address": { "type": "string", "description": "the address" }, "quota_mb": { "type": "integer", "description": "0 = no limit" }, "used_mb": { "type": "integer", "description": "space used" }, "send_only": { "type": "boolean", "description": "mail to it is refused" }, "created_at": { "type": "string", "description": "UTC" } } }, "MailImport": { "type": "object", "description": "A mail import from another provider", "properties": { "id": { "type": "integer", "description": "its id" }, "mailbox": { "type": "string", "description": "the address copied into" }, "source": { "type": "string", "description": "login @ old server" }, "status": { "type": "string", "description": "queued, running, cancelling, done, failed or cancelled" }, "folders": { "type": "integer", "description": "folders to copy" }, "folders_done": { "type": "integer", "description": "folders copied" }, "messages": { "type": "integer", "description": "messages on the old server" }, "copied": { "type": "integer", "description": "messages copied" }, "skipped": { "type": "integer", "description": "messages already there" }, "errors": { "type": "integer", "description": "messages that failed" }, "current_folder": { "type": "string", "description": "the folder being copied" }, "created_at": { "type": "string", "description": "UTC" }, "result": { "type": "string", "description": "the closing line" } } }, "Forwarder": { "type": "object", "description": "A forwarder", "properties": { "source": { "type": "string", "description": "the address, or *@domain" }, "destinations": { "type": "array", "items": { "type": "string" }, "description": "where it goes" }, "created_at": { "type": "string", "description": "UTC" } } }, "Certificate": { "type": "object", "description": "A domain's certificate", "properties": { "domain": { "type": "string", "description": "the domain" }, "type": { "type": "string", "description": "none, or the kind of certificate" }, "expires": { "type": [ "string", "null" ], "description": "when it ends" }, "days_left": { "type": [ "integer", "null" ], "description": "days until then" }, "issuer": { "type": [ "string", "null" ], "description": "who issued it" }, "names": { "type": [ "string", "null" ], "description": "the names it covers" }, "force_https": { "type": "boolean", "description": "visitors are sent to https://" }, "autossl": { "type": "boolean", "description": "AutoSSL looks after it" }, "autossl_note": { "type": "string", "description": "why AutoSSL is waiting" } } }, "DomainSSL": { "type": "object", "description": "A domain's SSL settings", "properties": { "domain": { "type": "string", "description": "the domain" }, "ssl": { "type": "boolean", "description": "has a certificate" }, "type": { "type": "string", "description": "le, custom or none" }, "expires": { "type": [ "string", "null" ], "description": "when it ends" }, "force_https": { "type": "boolean", "description": "visitors are sent to https://" }, "autossl": { "type": "boolean", "description": "AutoSSL looks after it" } } }, "Backup": { "type": "object", "description": "A backup", "properties": { "name": { "type": "string", "description": "its name" }, "size": { "type": [ "integer", "null" ], "description": "bytes" }, "created_at": { "type": "string", "description": "UTC" } } }, "BackupTarget": { "type": "object", "description": "A place of the account's own backup storage (no secrets)", "properties": { "id": { "type": "integer", "description": "its id" }, "name": { "type": "string", "description": "its name" }, "kind": { "type": "string", "description": "s3 or sftp" }, "summary": { "type": "string", "description": "where the copies go" }, "path": { "type": "string", "description": "the folder there" }, "freq": { "type": "string", "description": "off, daily or weekly" }, "weekday": { "type": "integer", "description": "weekly: 0 = Sunday" }, "hour": { "type": "integer", "description": "UTC" }, "keep_days": { "type": "integer", "description": "days copies are kept" }, "next_run": { "type": "integer", "description": "Unix time (0 = off)" }, "last": { "type": [ "object", "null" ], "description": "the last copy: time, ok, result" }, "test": { "type": [ "object", "null" ], "description": "the last test: ok, msg, at" } } }, "SSHKey": { "type": "object", "description": "An SSH public key", "properties": { "id": { "type": "integer", "description": "its id" }, "name": { "type": "string", "description": "its name" }, "type": { "type": "string", "description": "ssh-ed25519, ecdsa-sha2-…, ssh-rsa …" }, "bits": { "type": "integer", "description": "its size" }, "fingerprint": { "type": "string", "description": "SHA256:…" }, "comment": { "type": "string", "description": "the key's comment" }, "weak": { "type": "boolean", "description": "weaker than what is accepted now (an old short RSA key)" }, "created_at": { "type": "string", "description": "the day it was added" } } }, "WordPressSite": { "type": "object", "description": "A WordPress site and its safe updates", "properties": { "id": { "type": "integer", "description": "the site's id ({site} in the address)" }, "folder": { "type": "string", "description": "its folder in the account (web/…)" }, "url": { "type": "string", "description": "its address" }, "version": { "type": "string", "description": "the WordPress version" }, "updates": { "type": "integer", "description": "updates waiting" }, "core_update": { "type": "string", "description": "the WordPress version to update to (\"\" = none)" }, "vulnerabilities": { "type": "integer", "description": "known security problems" }, "vulnerable": { "type": "array", "items": { "type": "string" }, "description": "what has them, as kind:slug" }, "mode": { "type": "string", "description": "off, notify or auto" }, "schedule": { "type": "string", "description": "daily or weekly" }, "last_status": { "type": [ "string", "null" ], "description": "ok, rolled-back, failed or available" }, "last_run_at": { "type": [ "string", "null" ], "description": "UTC" }, "next_run_at": { "type": [ "string", "null" ], "description": "UTC" }, "running": { "type": "boolean", "description": "a run is going on or queued" } } }, "WordPressRun": { "type": "object", "description": "A safe update that was started", "properties": { "site": { "type": "integer", "description": "the site's id" }, "queued": { "type": "boolean", "description": "the run starts in the background" }, "items": { "type": "array", "items": { "type": "string" }, "description": "the items asked for (empty = everything the policy covers)" } } }, "CronJob": { "type": "object", "description": "A cron job", "properties": { "id": { "type": "integer", "description": "its id" }, "schedule": { "type": "string", "description": "5 fields" }, "command": { "type": "string", "description": "the command" }, "created_at": { "type": "string", "description": "UTC" } } }, "FtpAccount": { "type": "object", "description": "An FTP account", "properties": { "login": { "type": "string", "description": "name@domain" }, "folder": { "type": "string", "description": "the folder it sees (web/…)" }, "quota_mb": { "type": "integer", "description": "0 = no limit" }, "created_at": { "type": "string", "description": "UTC" } } }, "Monitor": { "type": "object", "description": "An uptime monitor", "properties": { "id": { "type": "integer", "description": "its id" }, "name": { "type": "string", "description": "its name" }, "kind": { "type": "string", "description": "http, tcp or ping" }, "target": { "type": "string", "description": "what it checks" }, "url": { "type": "string", "description": "http: the address" }, "host": { "type": "string", "description": "tcp and ping: the host" }, "port": { "type": "integer", "description": "tcp: the port" }, "interval_min": { "type": "integer", "description": "minutes between checks" }, "status": { "type": "string", "description": "up, down or unknown" }, "paused": { "type": "boolean", "description": "no checks while paused" }, "uptime_24h": { "type": [ "number", "null" ], "description": "percent" }, "uptime_30d": { "type": [ "number", "null" ], "description": "percent" }, "last_check": { "type": [ "string", "null" ], "description": "UTC" }, "last_ms": { "type": "integer", "description": "the last response time" }, "last_error": { "type": "string", "description": "why the last check failed" }, "ssl_expires": { "type": [ "string", "null" ], "description": "when the certificate ends (UTC)" }, "public": { "type": "boolean", "description": "on the status page" } } }, "Service": { "type": "object", "description": "A service", "properties": { "name": { "type": "string", "description": "its name" }, "state": { "type": "string", "description": "active, inactive, failed …" }, "running": { "type": "boolean", "description": "state is active" } } }, "Version": { "type": "object", "description": "The panel's version", "properties": { "version": { "type": "string", "description": "installed" }, "latest": { "type": [ "string", "null" ], "description": "the newest release" }, "published": { "type": [ "string", "null" ], "description": "its date" }, "newer": { "type": "boolean", "description": "an update is available" }, "update_running": { "type": "boolean", "description": "an update is running" }, "auto_update": { "type": "boolean", "description": "automatic updates are on" }, "checked_at": { "type": [ "string", "null" ], "description": "the last check (UTC)" }, "error": { "type": "string", "description": "the last check's error" } } }, "ServerUpdates": { "type": "object", "description": "Operating system updates", "properties": { "updates": { "type": "integer", "description": "packages that can be updated" }, "security": { "type": "integer", "description": "of them security updates" }, "checked": { "type": "string", "description": "when it was last checked" }, "running": { "type": "boolean", "description": "an update is installing now" }, "reboot_required": { "type": "boolean", "description": "the server needs a restart" }, "os": { "type": "string", "description": "the operating system" }, "kernel": { "type": "string", "description": "the kernel" }, "log": { "type": "array", "items": { "type": "string" }, "description": "the last lines of the update log" }, "error": { "type": [ "string", "null" ], "description": "why the agent couldn't answer" } } }, "FirewallRule": { "type": "object", "description": "A firewall rule", "properties": { "id": { "type": "integer", "description": "its number (the id to delete it with)" }, "to": { "type": "string", "description": "port or service" }, "action": { "type": "string", "description": "ALLOW, DENY, REJECT or LIMIT" }, "from": { "type": "string", "description": "where from" }, "ssh": { "type": "boolean", "description": "it keeps SSH open" } } }, "FirewallBan": { "type": "object", "description": "An address fail2ban has banned", "properties": { "ip": { "type": "string", "description": "the address" }, "jail": { "type": "string", "description": "the jail that banned it" } } }, "IpBlock": { "type": "object", "description": "An address or range blocked from the whole server", "properties": { "id": { "type": "integer", "description": "its rule number" }, "ip": { "type": "string", "description": "the address or range" } } }, "ActivityEntry": { "type": "object", "description": "A line of the activity log", "properties": { "at": { "type": "string", "description": "UTC" }, "account": { "type": [ "string", "null" ], "description": "who" }, "action": { "type": "string", "description": "what" }, "detail": { "type": "string", "description": "details" }, "ip": { "type": "string", "description": "from" } } }, "StaffLogin": { "type": "object", "description": "An administrator login", "properties": { "id": { "type": "integer", "description": "its id" }, "username": { "type": "string", "description": "its name" }, "email": { "type": "string", "description": "its email" }, "access": { "type": "string", "description": "full or read-only" }, "two_factor": { "type": "boolean", "description": "two-factor login is on" }, "self": { "type": "boolean", "description": "the login of this token" } } }, "Payment": { "type": "object", "description": "A payment received (a paid invoice)", "properties": { "id": { "type": "integer", "description": "the invoice's id" }, "invoice": { "type": "string", "description": "its number" }, "account": { "type": "string", "description": "the customer" }, "amount": { "type": "number", "description": "paid" }, "currency": { "type": "string", "description": "lower case" }, "method": { "type": "string", "description": "stripe, paypal, manual …" }, "paid_at": { "type": "string", "description": "UTC" } } }, "Product": { "type": "object", "description": "A package as it is sold", "properties": { "id": { "type": "integer", "description": "its id" }, "name": { "type": "string", "description": "its name" }, "price_month": { "type": "number", "description": "monthly price" }, "disk_mb": { "type": "integer", "description": "disk space" }, "max_domains": { "type": "integer", "description": "domains" }, "max_databases": { "type": "integer", "description": "databases" }, "max_mailboxes": { "type": "integer", "description": "mailboxes" }, "trial_days": { "type": "integer", "description": "free trial days" } } }, "Order": { "type": "object", "description": "A domain order", "properties": { "id": { "type": "integer", "description": "its id" }, "kind": { "type": "string", "description": "register, renew, transfer …" }, "domain": { "type": "string", "description": "the domain" }, "years": { "type": "integer", "description": "years" }, "amount": { "type": "number", "description": "price" }, "currency": { "type": "string", "description": "currency" }, "status": { "type": "string", "description": "unpaid, paid, done, failed …" }, "account": { "type": "string", "description": "the customer" }, "invoice": { "type": "string", "description": "its invoice number" }, "error": { "type": "string", "description": "why it failed" }, "created_at": { "type": "string", "description": "UTC" }, "done_at": { "type": [ "string", "null" ], "description": "when it was done" } } }, "GitRepo": { "type": "object", "description": "A Git repository of the account", "properties": { "id": { "type": "integer", "description": "its id" }, "name": { "type": "string", "description": "its name (the folder in ~/web/repositories)" }, "url": { "type": "string", "description": "where it was cloned from (no credentials)" }, "deploy": { "type": "string", "description": "the website folder inside web/ it is deployed to (empty: none)" }, "last_deploy": { "type": [ "string", "null" ], "description": "when it was last deployed (UTC)" }, "branch": { "type": "string", "description": "one repository: the branch it is on" }, "branches": { "type": "array", "items": { "type": "string" }, "description": "one repository: its branches" }, "remote": { "type": "string", "description": "one repository: the remote" }, "changes": { "type": "integer", "description": "one repository: uncommitted changes" }, "commits": { "type": "array", "items": { "type": "object" }, "description": "one repository: recent commits (hash, date, author, subject)" } } }, "App": { "type": "object", "description": "A Node.js, Python or Ruby app of the account", "properties": { "id": { "type": "integer", "description": "its id" }, "name": { "type": "string", "description": "its name" }, "domain": { "type": "string", "description": "the website it takes over" }, "root": { "type": "string", "description": "its folder in the account" }, "state": { "type": "string", "description": "active, inactive, failed … or unknown" }, "port": { "type": "integer", "description": "the port it listens on" }, "env": { "type": "object", "description": "its environment variables" }, "created_at": { "type": "string", "description": "UTC" }, "kind": { "type": "string", "description": "node: server or static" }, "mode": { "type": "string", "description": "node: production or development" }, "node": { "type": "string", "description": "node: the Node.js version" }, "install": { "type": "string", "description": "node: npm, npm-ci, yarn, pnpm or none" }, "build": { "type": "string", "description": "node: the package.json script that builds it" }, "start_cmd": { "type": "string", "description": "node: the start command" }, "outdir": { "type": "string", "description": "node: the build folder of a static site" }, "framework": { "type": "string", "description": "node: what was detected" }, "entry": { "type": "string", "description": "python: module:object; ruby: the rackup file" }, "server": { "type": "string", "description": "python: wsgi or asgi" }, "python": { "type": "string", "description": "python: the Python version" }, "workers": { "type": "integer", "description": "python and ruby: worker processes" } } }, "RedisStatus": { "type": "object", "description": "An account's Redis cache", "properties": { "enabled": { "type": "boolean", "description": "Redis is on" }, "running": { "type": "boolean", "description": "it is running" }, "memory_mb": { "type": "integer", "description": "its size" }, "sizes": { "type": "array", "items": { "type": "integer" }, "description": "the sizes the package allows (MB)" }, "version": { "type": "string", "description": "the Redis version" }, "used": { "type": "string", "description": "memory in use" }, "keys": { "type": "string", "description": "keys stored" }, "evicted": { "type": "string", "description": "keys evicted" }, "hit_rate": { "type": "string", "description": "cache hits" }, "socket": { "type": "string", "description": "its socket" }, "wordpress": { "type": "array", "items": { "type": "object" }, "description": "the WordPress sites: id, url, object_cache" } } }, "MemcachedStatus": { "type": "object", "description": "An account's Memcached", "properties": { "enabled": { "type": "boolean", "description": "Memcached is on" }, "running": { "type": "boolean", "description": "it is running" }, "memory_mb": { "type": "integer", "description": "its size" }, "sizes": { "type": "array", "items": { "type": "integer" }, "description": "the sizes the package allows (MB; empty: the package has no Memcached)" }, "version": { "type": "string", "description": "the Memcached version" }, "used": { "type": "string", "description": "memory in use" }, "items": { "type": "string", "description": "items stored" }, "evicted": { "type": "string", "description": "items evicted" }, "hit_rate": { "type": "string", "description": "cache hits" }, "socket": { "type": "string", "description": "its socket (what the website connects to)" } } }, "DockerApp": { "type": "object", "description": "A Docker app of the account", "properties": { "name": { "type": "string", "description": "its name" }, "app": { "type": "string", "description": "the catalogue key (e.g. uptime-kuma)" }, "title": { "type": "string", "description": "its title" }, "domain": { "type": "string", "description": "the domain it is served on" }, "status": { "type": "string", "description": "running, exited …" }, "running": { "type": "boolean", "description": "it is running" }, "memory_mb": { "type": "integer", "description": "memory in use" }, "password": { "type": "string", "description": "only when installed: the admin password it was given (shown once)" } } }, "DockerCatalogApp": { "type": "object", "description": "An app that can be installed as a Docker app", "properties": { "key": { "type": "string", "description": "its key" }, "title": { "type": "string", "description": "its name" }, "description": { "type": "string", "description": "what it is" }, "memory_mb": { "type": "integer", "description": "memory it needs" } } }, "LogView": { "type": "object", "description": "A website's log, or the explained errors", "properties": { "type": { "type": "string", "description": "errors, access, error, php or raw" }, "domain": { "type": [ "string", "null" ], "description": "the website" }, "file": { "type": "string", "description": "the log file in the account" }, "error": { "type": [ "string", "null" ], "description": "why it can't be shown (no log yet)" }, "size": { "type": "string", "description": "its size" }, "lines": { "type": "array", "items": { "type": "object" }, "description": "the last 300 lines, newest first (text, level)" }, "groups": { "type": "array", "items": { "type": "object" }, "description": "type errors: the errors grouped and explained" }, "files": { "type": "array", "items": { "type": "object" }, "description": "type raw: the files in ~/logs" } } }, "AccountBlock": { "type": "object", "description": "An address or range blocked on every website of the account", "properties": { "id": { "type": "integer", "description": "its id" }, "cidr": { "type": "string", "description": "the address or range" }, "note": { "type": "string", "description": "a note" }, "expires_at": { "type": [ "string", "null" ], "description": "when the block ends (UTC; null: never)" }, "created_at": { "type": "string", "description": "UTC" } } }, "Autoresponder": { "type": "object", "description": "A mailbox's autoresponder", "properties": { "address": { "type": "string", "description": "the mailbox" }, "enabled": { "type": "boolean", "description": "it is on" }, "subject": { "type": "string", "description": "the reply's subject" }, "body": { "type": "string", "description": "the reply's text" }, "days": { "type": "integer", "description": "days before the same sender gets it again" }, "start": { "type": "string", "description": "first day, YYYY-MM-DD" }, "end": { "type": "string", "description": "last day, YYYY-MM-DD" } } }, "Database": { "type": "object", "description": "A database of the account", "properties": { "name": { "type": "string", "description": "its full name" }, "engine": { "type": "string", "description": "mysql or postgres" }, "user": { "type": "string", "description": "postgres: its owner user" }, "created_at": { "type": "string", "description": "UTC" } } }, "CronRun": { "type": "object", "description": "One run of a cron job", "properties": { "started_at": { "type": "integer", "description": "unix time" }, "ended_at": { "type": "integer", "description": "unix time" }, "duration": { "type": "integer", "description": "seconds" }, "code": { "type": "integer", "description": "exit code" }, "output": { "type": "string", "description": "what it printed" }, "truncated": { "type": "boolean", "description": "the output was cut" }, "manual": { "type": "boolean", "description": "started by hand" } } }, "Redirect": { "type": "object", "description": "A redirect, a whole-site redirect or a blocked address of a website", "properties": { "id": { "type": "integer", "description": "its id" }, "domain": { "type": "string", "description": "the website" }, "kind": { "type": "string", "description": "redirect (one path), whole (the whole site) or block (an address)" }, "path": { "type": [ "string", "null" ], "description": "redirect: the path on the site" }, "target": { "type": [ "string", "null" ], "description": "redirect and whole: where visitors go; block: the address or range" }, "code": { "type": [ "integer", "null" ], "description": "301 or 302" } } }, "ErrorPage": { "type": "object", "description": "A website's page for one error code", "properties": { "domain": { "type": "string", "description": "the website" }, "code": { "type": "integer", "description": "the HTTP error code" }, "label": { "type": "string", "description": "its name" }, "custom": { "type": "boolean", "description": "the website has its own page for it (false: the standard page)" }, "html": { "type": [ "string", "null" ], "description": "the page's HTML (only when asked for one page)" }, "template": { "type": [ "string", "null" ], "description": "a page to start from (one page)" } } }, "PhpSettings": { "type": "object", "description": "An account's PHP version and settings", "properties": { "version": { "type": "string", "description": "the PHP version of the account's websites" }, "versions": { "type": "array", "items": { "type": "string" }, "description": "the versions you can choose" }, "settings": { "type": "object", "description": "memory_limit, upload_max_filesize, post_max_size, max_execution_time, max_input_time, max_input_vars, display_errors, date.timezone" }, "extensions": { "type": "array", "items": { "type": "string" }, "description": "the extensions that are on" }, "sites": { "type": "array", "items": { "type": "object" }, "description": "each website: domain, version, mode, page_cache" } } }, "PhpSite": { "type": "object", "description": "One website's PHP version, web server mode, page cache and settings", "properties": { "domain": { "type": "string", "description": "the website" }, "version": { "type": "string", "description": "its PHP version" }, "versions": { "type": "array", "items": { "type": "string" }, "description": "the versions you can choose" }, "mode": { "type": "string", "description": "nginx (Nginx only) or hybrid (Nginx and Apache: .htaccess works)" }, "page_cache": { "type": "integer", "description": "minutes pages are kept (0 = off)" }, "settings": { "type": "object", "description": "the settings in its .user.ini (the account's values apply to the rest)" } } }, "Ticket": { "type": "object", "description": "A support ticket", "properties": { "id": { "type": "integer", "description": "its number" }, "subject": { "type": "string", "description": "its subject" }, "status": { "type": "string", "description": "open (waiting for support), answered or closed" }, "priority": { "type": "string", "description": "low, normal or high" }, "domain": { "type": "string", "description": "the website it is about" }, "account": { "type": "string", "description": "staff: the customer" }, "email": { "type": "string", "description": "staff: the customer's email" }, "updated_at": { "type": "string", "description": "last activity (UTC)" }, "new": { "type": "boolean", "description": "list: there is something you haven't read" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "one ticket, staff: the customer's tags" }, "notes": { "type": "string", "description": "one ticket, staff: the customer's notes" }, "messages": { "type": "array", "items": { "type": "object" }, "description": "one ticket: from (customer or staff), author, at, body, via_email, files" } } }, "Webhook": { "type": "object", "description": "A webhook the panel calls when something happens", "properties": { "id": { "type": "integer", "description": "its id" }, "url": { "type": "string", "description": "where it is called" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the event keys it gets" }, "enabled": { "type": "boolean", "description": "it is on" }, "created_at": { "type": "integer", "description": "unix time" }, "secret": { "type": "string", "description": "only when made or renewed: the signing secret for X-HF-Signature (shown once)" } } }, "WebhookEvent": { "type": "object", "description": "An event the panel raises", "properties": { "key": { "type": "string", "description": "e.g. account.created" }, "name": { "type": "string", "description": "what it means" }, "example": { "type": "object", "description": "an example payload" } } }, "NotificationChannel": { "type": "object", "description": "Where a login's notifications go", "properties": { "id": { "type": "integer", "description": "its id" }, "kind": { "type": "string", "description": "email, webhook, slack, discord, telegram, whatsapp …" }, "name": { "type": "string", "description": "its name" }, "target": { "type": "string", "description": "where (address, host or chat)" }, "enabled": { "type": "boolean", "description": "it is on" }, "last_test": { "type": "string", "description": "when it was last tested" }, "last_test_ok": { "type": "boolean", "description": "the last test arrived" }, "secret": { "type": "string", "description": "webhook: only when made or renewed: the signing secret (shown once)" } } }, "NotificationSubscription": { "type": "object", "description": "An event sent to a channel", "properties": { "event": { "type": "string", "description": "the event key" }, "channel_id": { "type": "integer", "description": "the channel" } } }, "NotificationQuietHours": { "type": "object", "description": "When notifications are held", "properties": { "on": { "type": "boolean", "description": "quiet hours are on" }, "from": { "type": "string", "description": "HH:MM" }, "to": { "type": "string", "description": "HH:MM" }, "tz": { "type": "string", "description": "time zone, e.g. Europe/London" }, "urgent": { "type": "boolean", "description": "urgent events still come through" } } }, "NotificationEvent": { "type": "object", "description": "An event a login can subscribe to", "properties": { "key": { "type": "string", "description": "its key" }, "name": { "type": "string", "description": "its name" }, "description": { "type": "string", "description": "what it is" }, "group": { "type": "string", "description": "its group" }, "urgent": { "type": "boolean", "description": "on by default" } } }, "NotificationDelivery": { "type": "object", "description": "One notification that was sent (or not)", "properties": { "id": { "type": "integer", "description": "its id" }, "when": { "type": "string", "description": "UTC" }, "event": { "type": "string", "description": "the event" }, "title": { "type": "string", "description": "its title" }, "channel": { "type": "string", "description": "the channel" }, "status": { "type": "string", "description": "sent, pending, retry, held, failed or limited" }, "attempts": { "type": "integer", "description": "tries" }, "error": { "type": "string", "description": "why it failed" }, "test": { "type": "boolean", "description": "a test message" } } } } } }