{ "openapi": "3.1.0", "info": { "title": "Apohost API", "version": "1.0.0", "description": "Static site hosting with a simple agent-friendly API. Upload a zip or a set of files, get a URL. Authentication: `Authorization: Bearer ` with a personal token or ADMIN_TOKEN." }, "servers": [ { "url": "https://apohost.solutionbridge.win" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "A personal API token (create one in the dashboard) or the instance ADMIN_TOKEN." } }, "schemas": { "Site": { "type": "object", "properties": { "id": { "type": "string" }, "subdomain": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "custom_domains": { "type": "array", "items": { "type": "string" } }, "name": { "type": "string" }, "size_bytes": { "type": "integer" }, "hits": { "type": "integer" }, "created_at": { "type": "integer", "description": "unix ms" }, "updated_at": { "type": "integer", "description": "unix ms" } } } } }, "paths": { "/api/ping": { "get": { "summary": "Health check", "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } } } } }, "/api/me": { "get": { "summary": "Current account", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Account info", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "is_admin": { "type": "boolean" }, "tokens": { "type": "integer" }, "sites_used": { "type": "integer" }, "sites_limit": { "type": "integer" }, "storage_used_bytes": { "type": "integer" }, "storage_limit_bytes": { "type": "integer" } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/api/tokens": { "post": { "summary": "Create an API token", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "default": "api" } } } } } }, "responses": { "201": { "description": "Created token (value shown once)", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "token": { "type": "string" } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } }, "get": { "summary": "List API tokens", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Token list (hashed; values are never shown again)", "content": { "application/json": { "schema": { "type": "object", "properties": { "tokens": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "created_at": { "type": "integer" }, "last_used_at": { "type": "integer", "nullable": true } } } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/api/tokens/{id}": { "delete": { "summary": "Delete an API token", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted" }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/api/sites": { "get": { "summary": "List your sites", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Site list", "content": { "application/json": { "schema": { "type": "object", "properties": { "sites": { "type": "array", "items": { "$ref": "#/components/schemas/Site" } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } }, "post": { "summary": "Create a site from a zip archive", "description": "Upload `multipart/form-data` with fields `name` (site name, becomes .) and `file` (a .zip archive, max 100 MB), or send the raw zip as the request body with `?name=` in the query string. The zip should contain your site files (index.html at the archive root or in a single top-level folder).", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Site name; lowercase letters, digits and dashes" }, "file": { "type": "string", "format": "binary", "description": ".zip archive of the site" } }, "required": [ "name", "file" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Site" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "402": { "description": "Quota exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Name taken", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "413": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/api/sites/{subdomain}": { "get": { "summary": "Get one of your sites", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "subdomain", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Site", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Site" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } }, "delete": { "summary": "Delete one of your sites", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "subdomain", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted" }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/api/sites/{subdomain}/files": { "put": { "summary": "Deploy files to a site (creates the site if it does not exist)", "description": "Send JSON: `{ \"files\": [{ \"path\": \"index.html\", \"content\": \"

Hello

\" }] }` — use `content` for UTF-8 text or `content_base64` for binary files. Replaces the whole site contents; creates the site on first deploy. This is the one-call publish endpoint for agents.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "subdomain", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "files": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "content": { "type": "string", "description": "UTF-8 file content (for text files)" }, "content_base64": { "type": "string", "description": "Base64-encoded file content (for binary files)" } }, "anyOf": [ { "required": [ "path", "content" ] }, { "required": [ "path", "content_base64" ] } ] } } }, "required": [ "files" ] } } } }, "responses": { "200": { "description": "Deployed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Site" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "413": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/api/sites/{subdomain}/domains": { "get": { "summary": "List custom domains for a site", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "subdomain", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Domain list", "content": { "application/json": { "schema": { "type": "object", "properties": { "domains": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "verified": { "type": "boolean" } } } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } }, "post": { "summary": "Add a custom domain to a site", "description": "Point a CNAME record for the domain at your Apohost host, then call this endpoint. DNS is verified server-side before the domain is added.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "subdomain", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string" } }, "required": [ "domain" ] } } } }, "responses": { "201": { "description": "Domain added (verified)", "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string" }, "verified": { "type": "boolean" } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/api/sites/{subdomain}/domains/{domain}": { "delete": { "summary": "Remove a custom domain from a site", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "subdomain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Removed" }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/api/domains/check": { "get": { "summary": "On-demand TLS allow-list check (for Caddy/Traefik)", "description": "Called server-side by a reverse proxy before issuing a certificate for a custom domain. Returns 200 if the domain is connected to a site on this instance, 401 otherwise.", "parameters": [ { "name": "domain", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Domain is connected; issue certificate" }, "401": { "description": "Unknown domain" } } } }, "/api/admin/sites": { "get": { "summary": "List every site on this instance (admin only)", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "All sites", "content": { "application/json": { "schema": { "type": "object", "properties": { "sites": { "type": "array", "items": { "$ref": "#/components/schemas/Site" } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/api/admin/sites/{subdomain}": { "delete": { "summary": "Delete any site (admin takedown)", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "subdomain", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted" }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } } } }