{"openapi":"3.1.0","info":{"title":"Helstify API","version":"1.0.0","description":"Run your Helstify businesses from code: servers, files, DNS, mail, campaigns, tools, backups and the AI council."},"servers":[{"url":"https:\/\/helstify.com\/api\/v1"}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","bearerFormat":"hsk_\u2026"}}},"paths":{"\/me":{"get":{"tags":["Account"],"summary":"Get the account","description":"The account that owns this key, and what the key itself is allowed to do. Scope: `account:read`.","operationId":"get_me","security":[{"bearer":["account:read"]}],"parameters":[],"responses":{"200":{"description":"OK","content":{"application\/json":{"example":{"ok":true,"account":{"id":42,"name":"Asha Rao","email":"asha@example.com","plan":"operator","businesses":3,"billing_linked":true},"key":{"name":"Deploy bot","prefix":"hsk_8fK2pQ1m","scopes":["account:read","files:write"],"businesses":"all","expires_at":null,"rate_limit":120}}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}}}},"\/businesses":{"get":{"tags":["Account"],"summary":"List businesses","description":"Every business this key can open, owned or operated as a team member. Scope: `account:read`.","operationId":"get_businesses","security":[{"bearer":["account:read"]}],"parameters":[],"responses":{"200":{"description":"OK","content":{"application\/json":{"example":{"ok":true,"count":1,"businesses":[{"id":60,"name":"Northwind Coffee","status":"live","live":true,"domain":"northwind.coffee","kind":"web","reachable":true,"read_only":false,"owned":true}]}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}}}},"\/businesses\/{business}":{"get":{"tags":["Account"],"summary":"Get a business","description":"One business, with its domains, published hostnames and what the AI agents may do on it. Scope: `account:read`.","operationId":"get_businesses_business","security":[{"bearer":["account:read"]}],"parameters":[{"name":"business","in":"path","required":true,"description":"The business id, from GET \/businesses.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application\/json":{"example":{"ok":true,"business":{"id":60,"name":"Northwind Coffee","status":"live","kind":"web","domains":["northwind.coffee"],"hostnames":["northwind.coffee","shop.northwind.coffee"],"permissions":["files.read","files.write","dns.read"],"created_at":"2026-09-14T10:02:11Z"}}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}}}},"\/businesses\/{business}\/uptime":{"get":{"tags":["Account"],"summary":"Get uptime","description":"The last check of every hostname we watch for this business, and recent incidents. Uptime watch is part of the Operator and Studio plans. Scope: `account:read`.","operationId":"get_businesses_business_uptime","security":[{"bearer":["account:read"]}],"parameters":[{"name":"business","in":"path","required":true,"description":"The business id, from GET \/businesses.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application\/json":{"example":{"ok":true,"watched":true,"hosts":[{"hostname":"northwind.coffee","up":true,"error":null,"checked_at":"2026-11-09T08:41:00Z"}],"incidents":[{"hostname":"northwind.coffee","started_at":"2026-11-02T03:10:00Z","ended_at":"2026-11-02T03:16:00Z","error":"HTTP 502"}]}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}}}},"\/services":{"get":{"tags":["Billing"],"summary":"List services","description":"Every plan and hosting service on the account, with price and renewal date. Scope: `billing:read`.","operationId":"get_services","security":[{"bearer":["billing:read"]}],"parameters":[],"responses":{"200":{"description":"OK","content":{"application\/json":{"example":{"ok":true,"count":1,"services":[{"id":311,"category":"Plans","product":"Operator","status":"active","price":"$24.00 \/ month","renews_at":"2026-12-01","agent":null}]}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}}}},"\/invoices":{"get":{"tags":["Billing"],"summary":"List invoices","description":"The latest 100 invoices, newest first. Scope: `billing:read`.","operationId":"get_invoices","security":[{"bearer":["billing:read"]}],"parameters":[{"name":"status","in":"query","required":false,"description":"pending, paid or cancelled.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application\/json":{"example":{"ok":true,"count":1,"invoices":[{"id":1882,"status":"pending","total":"$24.00","due_at":"2026-12-01","created_at":"2026-11-24"}]}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}}}},"\/tickets":{"get":{"tags":["Billing"],"summary":"List support tickets","description":"Support conversations, newest first. Scope: `support:read`.","operationId":"get_tickets","security":[{"bearer":["support:read"]}],"parameters":[{"name":"status","in":"query","required":false,"description":"open, replied or closed.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application\/json":{"example":{"ok":true,"count":1,"tickets":[{"id":77,"subject":"Custom domain on the shop","status":"replied","updated_at":"2026-11-08 17:20:04"}]}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}}}},"\/businesses\/{business}\/files":{"get":{"tags":["Files and commands"],"summary":"List a folder","description":"The entries in one folder. Scope: `files:read`.","operationId":"get_businesses_business_files","security":[{"bearer":["files:read"]}],"parameters":[{"name":"business","in":"path","required":true,"description":"The business id, from GET \/businesses.","schema":{"type":"integer"}},{"name":"path","in":"query","required":false,"description":"The folder. Defaults to \/.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application\/json":{"example":{"ok":true,"business":"Northwind Coffee","entries":[{"name":"public","type":"dir","size":4096,"modified":1794172440,"mode":"drwxr-xr-x"},{"name":"composer.json","type":"file","size":1874,"modified":1793525412,"mode":"-rw-r--r--"}]}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}}}},"\/businesses\/{business}\/file":{"get":{"tags":["Files and commands"],"summary":"Read a file","description":"One text file's contents. Scope: `files:read`.","operationId":"get_businesses_business_file","security":[{"bearer":["files:read"]}],"parameters":[{"name":"business","in":"path","required":true,"description":"The business id, from GET \/businesses.","schema":{"type":"integer"}},{"name":"path","in":"query","required":true,"description":"The file to read.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application\/json":{"example":{"ok":true,"business":"Northwind Coffee","contents":"\n\u2026","truncated":false}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}}},"put":{"tags":["Files and commands"],"summary":"Write a file","description":"Create or replace one text file. Folders that do not exist yet are made. For binaries, upload an archive with \/copy or a command. Scope: `files:write`.","operationId":"put_businesses_business_file","security":[{"bearer":["files:write"]}],"parameters":[{"name":"business","in":"path","required":true,"description":"The business id, from GET \/businesses.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application\/json":{"example":{"ok":true,"business":"Northwind Coffee","written":"\/public\/hello.html","bytes":14}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}},"requestBody":{"required":true,"content":{"application\/json":{"example":{"path":"\/public\/hello.html","contents":"

Hello<\/h1>"}}}}}},"\/businesses\/{business}\/search":{"get":{"tags":["Files and commands"],"summary":"Search files","description":"Find files and folders whose name matches. Scope: `files:read`.","operationId":"get_businesses_business_search","security":[{"bearer":["files:read"]}],"parameters":[{"name":"business","in":"path","required":true,"description":"The business id, from GET \/businesses.","schema":{"type":"integer"}},{"name":"query","in":"query","required":true,"description":"Part of a file name.","schema":{"type":"string"}},{"name":"path","in":"query","required":false,"description":"Folder to search in.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application\/json":{"example":{"ok":true,"business":"Northwind Coffee","matches":[{"path":"\/resources\/views\/home.blade.php","type":"file","name":"home.blade.php"}]}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}}}},"\/businesses\/{business}\/copy":{"post":{"tags":["Files and commands"],"summary":"Copy from another business","description":"Copy one file into this business from another business on the same account. Binary-safe, streamed server to server. Both businesses must be within the key's reach. Scope: `files:write`.","operationId":"post_businesses_business_copy","security":[{"bearer":["files:write"]}],"parameters":[{"name":"business","in":"path","required":true,"description":"The business id, from GET \/businesses.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application\/json":{"example":{"ok":true,"business":"Northwind Coffee","copied":"\/tmp\/site.tgz","from_business":"Northwind Staging","bytes":18874368}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}},"requestBody":{"required":true,"content":{"application\/json":{"example":{"from":61,"from_path":"\/backups\/site.tgz","to_path":"\/tmp\/site.tgz"}}}}}},"\/businesses\/{business}\/extract":{"post":{"tags":["Files and commands"],"summary":"Unpack an archive","description":"Unpack a .zip, .tar or .tgz on the server. Scope: `files:write`.","operationId":"post_businesses_business_extract","security":[{"bearer":["files:write"]}],"parameters":[{"name":"business","in":"path","required":true,"description":"The business id, from GET \/businesses.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application\/json":{"example":{"ok":true,"business":"Northwind Coffee","extracted":"\/tmp\/site.tgz","into":"\/tmp\/site"}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}},"requestBody":{"required":true,"content":{"application\/json":{"example":{"path":"\/tmp\/site.tgz","to":"\/tmp\/site"}}}}}},"\/businesses\/{business}\/exec":{"post":{"tags":["Files and commands"],"summary":"Run a command","description":"Run one shell command inside the business's server. Up to 600 seconds. Refused on game servers; use \/console there. Scope: `commands:run`.","operationId":"post_businesses_business_exec","security":[{"bearer":["commands:run"]}],"parameters":[{"name":"business","in":"path","required":true,"description":"The business id, from GET \/businesses.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application\/json":{"example":{"ok":true,"business":"Northwind Coffee","exit_code":0,"stdout":"INFO Nothing to migrate.\n","stderr":""}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}},"requestBody":{"required":true,"content":{"application\/json":{"example":{"command":"php artisan migrate --force","cwd":"","timeout":120}}}}}},"\/businesses\/{business}\/logs":{"get":{"tags":["Files and commands"],"summary":"Read server logs","description":"The tail of one log. Scope: `files:read`.","operationId":"get_businesses_business_logs","security":[{"bearer":["files:read"]}],"parameters":[{"name":"business","in":"path","required":true,"description":"The business id, from GET \/businesses.","schema":{"type":"integer"}},{"name":"type","in":"query","required":false,"description":"nginx-error (default), nginx-access, php or laravel.","schema":{"type":"string"}},{"name":"lines","in":"query","required":false,"description":"How many lines. Default 200.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application\/json":{"example":{"ok":true,"business":"Northwind Coffee","type":"nginx-error","lines":["2026\/11\/09 08:12:44 [error] 41#41: *9 FastCGI sent in stderr: \u2026"]}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}}}},"\/businesses\/{business}\/state":{"get":{"tags":["Game servers"],"summary":"Get server state","description":"running, starting, stopping or offline. Scope: `files:read`.","operationId":"get_businesses_business_state","security":[{"bearer":["files:read"]}],"parameters":[{"name":"business","in":"path","required":true,"description":"The business id, from GET \/businesses.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application\/json":{"example":{"ok":true,"business":"StampedeMC","state":"running"}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}}}},"\/businesses\/{business}\/console":{"post":{"tags":["Game servers"],"summary":"Send a console command","description":"Send one command to the game console. Read \/logs for the answer. Scope: `commands:run`.","operationId":"post_businesses_business_console","security":[{"bearer":["commands:run"]}],"parameters":[{"name":"business","in":"path","required":true,"description":"The business id, from GET \/businesses.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application\/json":{"example":{"ok":true,"business":"StampedeMC","sent":"say Restarting in 5 minutes","note":"Read \/logs to see what the server answered."}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}},"requestBody":{"required":true,"content":{"application\/json":{"example":{"command":"say Restarting in 5 minutes"}}}}}},"\/businesses\/{business}\/power":{"post":{"tags":["Game servers"],"summary":"Start, stop or restart","description":"Players are disconnected by anything but start. Scope: `power`.","operationId":"post_businesses_business_power","security":[{"bearer":["power"]}],"parameters":[{"name":"business","in":"path","required":true,"description":"The business id, from GET \/businesses.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application\/json":{"example":{"ok":true,"business":"StampedeMC","signal":"restart"}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}},"requestBody":{"required":true,"content":{"application\/json":{"example":{"signal":"restart"}}}}}},"\/services\/{service}\/files":{"get":{"tags":["Hosting services"],"summary":"List a folder","description":"The entries in one folder. Scope: `files:read`.","operationId":"get_services_service_files","security":[{"bearer":["files:read"]}],"parameters":[{"name":"service","in":"path","required":true,"description":"The hosting service id, from GET \/services.","schema":{"type":"integer"}},{"name":"path","in":"query","required":false,"description":"Defaults to \/.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application\/json":{"example":{"ok":true,"service":"Minecraft \u00b7 Paper","entries":[{"name":"server.properties","type":"file","size":1402,"modified":1794150000,"mode":"-rw-r--r--"}]}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}}}},"\/services\/{service}\/file":{"get":{"tags":["Hosting services"],"summary":"Read a file","description":"One file's contents. Scope: `files:read`.","operationId":"get_services_service_file","security":[{"bearer":["files:read"]}],"parameters":[{"name":"service","in":"path","required":true,"description":"The hosting service id, from GET \/services.","schema":{"type":"integer"}},{"name":"path","in":"query","required":true,"description":"The file.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application\/json":{"example":{"ok":true,"service":"Minecraft \u00b7 Paper","contents":"motd=Welcome\nmax-players=40\n","truncated":false}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}}},"put":{"tags":["Hosting services"],"summary":"Write a file","description":"Create or replace one file. Scope: `files:write`.","operationId":"put_services_service_file","security":[{"bearer":["files:write"]}],"parameters":[{"name":"service","in":"path","required":true,"description":"The hosting service id, from GET \/services.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application\/json":{"example":{"ok":true,"service":"Minecraft \u00b7 Paper","written":"\/server.properties","bytes":18}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}},"requestBody":{"required":true,"content":{"application\/json":{"example":{"path":"\/server.properties","contents":"motd=Welcome back\n"}}}}},"delete":{"tags":["Hosting services"],"summary":"Delete a file","description":"Delete one file or folder. Scope: `files:write`.","operationId":"delete_services_service_file","security":[{"bearer":["files:write"]}],"parameters":[{"name":"service","in":"path","required":true,"description":"The hosting service id, from GET \/services.","schema":{"type":"integer"}},{"name":"path","in":"query","required":true,"description":"What to delete.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application\/json":{"example":{"ok":true,"service":"Minecraft \u00b7 Paper","deleted":"\/old-world"}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}}}},"\/services\/{service}\/folder":{"post":{"tags":["Hosting services"],"summary":"Make a folder","description":"Create a folder. Scope: `files:write`.","operationId":"post_services_service_folder","security":[{"bearer":["files:write"]}],"parameters":[{"name":"service","in":"path","required":true,"description":"The hosting service id, from GET \/services.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application\/json":{"example":{"ok":true,"service":"Minecraft \u00b7 Paper","created":"\/plugins\/config"}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}},"requestBody":{"required":true,"content":{"application\/json":{"example":{"path":"\/plugins\/config"}}}}}},"\/services\/{service}\/rename":{"post":{"tags":["Hosting services"],"summary":"Rename or move","description":"Rename a file or folder. Scope: `files:write`.","operationId":"post_services_service_rename","security":[{"bearer":["files:write"]}],"parameters":[{"name":"service","in":"path","required":true,"description":"The hosting service id, from GET \/services.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application\/json":{"example":{"ok":true,"service":"Minecraft \u00b7 Paper","from":"\/world","to":"\/world-old"}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}},"requestBody":{"required":true,"content":{"application\/json":{"example":{"from":"\/world","to":"\/world-old"}}}}}},"\/services\/{service}\/extract":{"post":{"tags":["Hosting services"],"summary":"Unpack an archive","description":"Unpacks next to the archive. Scope: `files:write`.","operationId":"post_services_service_extract","security":[{"bearer":["files:write"]}],"parameters":[{"name":"service","in":"path","required":true,"description":"The hosting service id, from GET \/services.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application\/json":{"example":{"ok":true,"service":"Minecraft \u00b7 Paper","extracted":"\/world.zip","into":"\/"}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}},"requestBody":{"required":true,"content":{"application\/json":{"example":{"path":"\/world.zip"}}}}}},"\/services\/{service}\/logs":{"get":{"tags":["Hosting services"],"summary":"Read console output","description":"The server's recent console output. Scope: `files:read`.","operationId":"get_services_service_logs","security":[{"bearer":["files:read"]}],"parameters":[{"name":"service","in":"path","required":true,"description":"The hosting service id, from GET \/services.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application\/json":{"example":{"ok":true,"service":"Minecraft \u00b7 Paper","lines":["[08:40:02 INFO]: Done (4.1s)! For help, type \"help\""]}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}}}},"\/services\/{service}\/state":{"get":{"tags":["Hosting services"],"summary":"Get server state","description":"running, starting, stopping or offline. Scope: `files:read`.","operationId":"get_services_service_state","security":[{"bearer":["files:read"]}],"parameters":[{"name":"service","in":"path","required":true,"description":"The hosting service id, from GET \/services.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application\/json":{"example":{"ok":true,"service":"Minecraft \u00b7 Paper","state":"running"}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}}}},"\/services\/{service}\/console":{"post":{"tags":["Hosting services"],"summary":"Send a console command","description":"Not a shell. Scope: `commands:run`.","operationId":"post_services_service_console","security":[{"bearer":["commands:run"]}],"parameters":[{"name":"service","in":"path","required":true,"description":"The hosting service id, from GET \/services.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application\/json":{"example":{"ok":true,"service":"Minecraft \u00b7 Paper","sent":"whitelist add Steve"}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}},"requestBody":{"required":true,"content":{"application\/json":{"example":{"command":"whitelist add Steve"}}}}}},"\/services\/{service}\/power":{"post":{"tags":["Hosting services"],"summary":"Start, stop or restart","description":"start, stop, restart or kill. Scope: `power`.","operationId":"post_services_service_power","security":[{"bearer":["power"]}],"parameters":[{"name":"service","in":"path","required":true,"description":"The hosting service id, from GET \/services.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application\/json":{"example":{"ok":true,"service":"Minecraft \u00b7 Paper","signal":"start"}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}},"requestBody":{"required":true,"content":{"application\/json":{"example":{"signal":"start"}}}}}},"\/businesses\/{business}\/dns\/zones":{"get":{"tags":["Domains and DNS"],"summary":"List zones","description":"The domains you can manage, our nameservers and the server IP. Scope: `dns:read`.","operationId":"get_businesses_business_dns_zones","security":[{"bearer":["dns:read"]}],"parameters":[{"name":"business","in":"path","required":true,"description":"The business id, from GET \/businesses.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application\/json":{"example":{"server_ip":"92.118.206.162","nameservers":["ns1.helstify.com","ns2.helstify.com"],"zones":[{"domain":"northwind.coffee","delegated":true,"records":9}]}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}}}},"\/businesses\/{business}\/dns\/records":{"get":{"tags":["Domains and DNS"],"summary":"List records","description":"Every record in one zone. Scope: `dns:read`.","operationId":"get_businesses_business_dns_records","security":[{"bearer":["dns:read"]}],"parameters":[{"name":"business","in":"path","required":true,"description":"The business id, from GET \/businesses.","schema":{"type":"integer"}},{"name":"domain","in":"query","required":false,"description":"Defaults to the primary domain.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application\/json":{"example":{"domain":"northwind.coffee","delegated":true,"records":[{"id":812,"type":"A","name":"@","content":"92.118.206.162","ttl":3600,"priority":null,"fqdn":"northwind.coffee"}]}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}}},"post":{"tags":["Domains and DNS"],"summary":"Create a record","description":"name \"@\" is the apex. priority is only for MX and SRV. Scope: `dns:write`.","operationId":"post_businesses_business_dns_records","security":[{"bearer":["dns:write"]}],"parameters":[{"name":"business","in":"path","required":true,"description":"The business id, from GET \/businesses.","schema":{"type":"integer"}}],"responses":{"201":{"description":"OK","content":{"application\/json":{"example":{"record":{"id":813,"type":"TXT","name":"@","content":"v=spf1 mx -all","ttl":3600,"priority":null,"fqdn":"northwind.coffee"}}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}},"requestBody":{"required":true,"content":{"application\/json":{"example":{"domain":"northwind.coffee","type":"TXT","name":"@","content":"v=spf1 mx -all","ttl":3600}}}}}},"\/businesses\/{business}\/dns\/records\/{record}":{"patch":{"tags":["Domains and DNS"],"summary":"Update a record","description":"Same fields as create; send only what changes. Scope: `dns:write`.","operationId":"patch_businesses_business_dns_records_record","security":[{"bearer":["dns:write"]}],"parameters":[{"name":"business","in":"path","required":true,"description":"The business id, from GET \/businesses.","schema":{"type":"integer"}},{"name":"record","in":"path","required":true,"description":"The record id.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application\/json":{"example":{"record":{"id":812,"type":"A","name":"@","content":"92.118.206.170","ttl":3600,"priority":null,"fqdn":"northwind.coffee"}}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}},"requestBody":{"required":true,"content":{"application\/json":{"example":{"content":"92.118.206.170"}}}}},"delete":{"tags":["Domains and DNS"],"summary":"Delete a record","description":"Removes it from our nameservers. Scope: `dns:write`.","operationId":"delete_businesses_business_dns_records_record","security":[{"bearer":["dns:write"]}],"parameters":[{"name":"business","in":"path","required":true,"description":"The business id, from GET \/businesses.","schema":{"type":"integer"}},{"name":"record","in":"path","required":true,"description":"The record id.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application\/json":{"example":{"deleted":true}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}}}},"\/businesses\/{business}\/routes":{"get":{"tags":["Site routes"],"summary":"List hostnames","description":"Every published hostname and where it points. Scope: `routes:read`.","operationId":"get_businesses_business_routes","security":[{"bearer":["routes:read"]}],"parameters":[{"name":"business","in":"path","required":true,"description":"The business id, from GET \/businesses.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application\/json":{"example":{"routes":[{"hostname":"shop.northwind.coffee","status":"live","url":"https:\/\/shop.northwind.coffee","error":null,"live_since":"2026-10-30T12:04:00+00:00"}]}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}}},"post":{"tags":["Site routes"],"summary":"Publish a hostname","description":"Serve a hostname from this business. Poll the list until its status is live. Scope: `routes:write`.","operationId":"post_businesses_business_routes","security":[{"bearer":["routes:write"]}],"parameters":[{"name":"business","in":"path","required":true,"description":"The business id, from GET \/businesses.","schema":{"type":"integer"}}],"responses":{"201":{"description":"OK","content":{"application\/json":{"example":{"route":{"hostname":"shop.northwind.coffee","status":"pending","url":"https:\/\/shop.northwind.coffee","error":null,"live_since":null},"note":"Serving is being set up. Poll GET \/routes until status is \"live\"."}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}},"requestBody":{"required":true,"content":{"application\/json":{"example":{"hostname":"shop.northwind.coffee"}}}}}},"\/businesses\/{business}\/routes\/{hostname}":{"delete":{"tags":["Site routes"],"summary":"Unpublish a hostname","description":"Takes that hostname offline. Scope: `routes:write`.","operationId":"delete_businesses_business_routes_hostname","security":[{"bearer":["routes:write"]}],"parameters":[{"name":"business","in":"path","required":true,"description":"The business id, from GET \/businesses.","schema":{"type":"integer"}},{"name":"hostname","in":"path","required":true,"description":"e.g. shop.northwind.coffee","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application\/json":{"example":{"ok":true}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}}}},"\/businesses\/{business}\/mail\/domains":{"get":{"tags":["Mail"],"summary":"List mail domains","description":"Domains with mail turned on. Scope: `mail:read`.","operationId":"get_businesses_business_mail_domains","security":[{"bearer":["mail:read"]}],"parameters":[{"name":"business","in":"path","required":true,"description":"The business id, from GET \/businesses.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application\/json":{"example":{"domains":[{"domain":"northwind.coffee","mailboxes":2}]}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}}}},"\/businesses\/{business}\/mail\/mailboxes":{"get":{"tags":["Mail"],"summary":"List mailboxes","description":"Every mailbox on one domain. Scope: `mail:read`.","operationId":"get_businesses_business_mail_mailboxes","security":[{"bearer":["mail:read"]}],"parameters":[{"name":"business","in":"path","required":true,"description":"The business id, from GET \/businesses.","schema":{"type":"integer"}},{"name":"domain","in":"query","required":false,"description":"Defaults to the primary domain.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application\/json":{"example":{"domain":"northwind.coffee","mailboxes":[{"id":31,"email":"hello@northwind.coffee","quota_mb":2048,"active":true,"by_agent":false,"has_password":true}]}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}}},"post":{"tags":["Mail"],"summary":"Create a mailbox","description":"Returns the new password once. Store it. Scope: `mail:write`.","operationId":"post_businesses_business_mail_mailboxes","security":[{"bearer":["mail:write"]}],"parameters":[{"name":"business","in":"path","required":true,"description":"The business id, from GET \/businesses.","schema":{"type":"integer"}}],"responses":{"201":{"description":"OK","content":{"application\/json":{"example":{"mailbox":{"id":32,"email":"orders@northwind.coffee","quota_mb":1024,"active":true,"by_agent":true,"has_password":true},"password":"q7M-\u2026"}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}},"requestBody":{"required":true,"content":{"application\/json":{"example":{"local_part":"orders","quota_mb":1024}}}}}},"\/businesses\/{business}\/mail\/mailboxes\/{mailbox}":{"patch":{"tags":["Mail"],"summary":"Update a mailbox","description":"Change quota, pause it, or rotate its password. Scope: `mail:write`.","operationId":"patch_businesses_business_mail_mailboxes_mailbox","security":[{"bearer":["mail:write"]}],"parameters":[{"name":"business","in":"path","required":true,"description":"The business id, from GET \/businesses.","schema":{"type":"integer"}},{"name":"mailbox","in":"path","required":true,"description":"The mailbox id, from GET \u2026\/mail\/mailboxes.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application\/json":{"example":{"mailbox":{"id":32,"email":"orders@northwind.coffee","quota_mb":4096,"active":true}}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}},"requestBody":{"required":true,"content":{"application\/json":{"example":{"quota_mb":4096,"rotate_password":false}}}}},"delete":{"tags":["Mail"],"summary":"Delete a mailbox","description":"Deletes the mailbox and every message in it. Scope: `mail:write`.","operationId":"delete_businesses_business_mail_mailboxes_mailbox","security":[{"bearer":["mail:write"]}],"parameters":[{"name":"business","in":"path","required":true,"description":"The business id, from GET \/businesses.","schema":{"type":"integer"}},{"name":"mailbox","in":"path","required":true,"description":"The mailbox id, from GET \u2026\/mail\/mailboxes.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application\/json":{"example":{"deleted":true}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}}}},"\/businesses\/{business}\/mail\/mailboxes\/import":{"post":{"tags":["Mail"],"summary":"Import existing mailboxes","description":"Adopt mailboxes that already exist on the mail server for this domain. Scope: `mail:write`.","operationId":"post_businesses_business_mail_mailboxes_import","security":[{"bearer":["mail:write"]}],"parameters":[{"name":"business","in":"path","required":true,"description":"The business id, from GET \/businesses.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application\/json":{"example":{"imported":1,"mailboxes":[]}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}},"requestBody":{"required":true,"content":{"application\/json":{"example":{"domain":"northwind.coffee"}}}}}},"\/businesses\/{business}\/mail\/mailboxes\/{mailbox}\/messages":{"get":{"tags":["Mail"],"summary":"List messages","description":"Newest first. Scope: `mail:read`.","operationId":"get_businesses_business_mail_mailboxes_mailbox_messages","security":[{"bearer":["mail:read"]}],"parameters":[{"name":"business","in":"path","required":true,"description":"The business id, from GET \/businesses.","schema":{"type":"integer"}},{"name":"mailbox","in":"path","required":true,"description":"The mailbox id, from GET \u2026\/mail\/mailboxes.","schema":{"type":"integer"}},{"name":"folder","in":"query","required":false,"description":"INBOX by default.","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application\/json":{"example":{"folder":"INBOX","total":1,"messages":[{"uid":118,"from":"Sam ","subject":"Wholesale order","date":"2026-11-08T14:01:00Z","unread":true,"has_attachments":false,"preview":"Hi, could we get 20kg of\u2026"}]}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}}}},"\/businesses\/{business}\/mail\/mailboxes\/{mailbox}\/messages\/{uid}":{"get":{"tags":["Mail"],"summary":"Read a message","description":"The full message as text. Scope: `mail:read`.","operationId":"get_businesses_business_mail_mailboxes_mailbox_messages_uid","security":[{"bearer":["mail:read"]}],"parameters":[{"name":"business","in":"path","required":true,"description":"The business id, from GET \/businesses.","schema":{"type":"integer"}},{"name":"mailbox","in":"path","required":true,"description":"The mailbox id, from GET \u2026\/mail\/mailboxes.","schema":{"type":"integer"}},{"name":"uid","in":"path","required":true,"description":"The message uid.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application\/json":{"example":{"message":{"uid":118,"from":"Sam ","to":"orders@northwind.coffee","cc":"","subject":"Wholesale order","date":"2026-11-08T14:01:00Z","body":"Hi, could we get 20kg of the house blend\u2026","attachments":[]}}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}}}},"\/businesses\/{business}\/mail\/mailboxes\/{mailbox}\/send":{"post":{"tags":["Mail"],"summary":"Send an email","description":"Sent from that mailbox, with a copy in its Sent folder. Scope: `mail:send`.","operationId":"post_businesses_business_mail_mailboxes_mailbox_send","security":[{"bearer":["mail:send"]}],"parameters":[{"name":"business","in":"path","required":true,"description":"The business id, from GET \/businesses.","schema":{"type":"integer"}},{"name":"mailbox","in":"path","required":true,"description":"The mailbox id, from GET \u2026\/mail\/mailboxes.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application\/json":{"example":{"sent":true}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}},"requestBody":{"required":true,"content":{"application\/json":{"example":{"to":"sam@example.com","subject":"Re: Wholesale order","body":"Yes, we can ship on Thursday."}}}}}},"\/businesses\/{business}\/marketing\/overview":{"get":{"tags":["Email marketing"],"summary":"Overview","description":"Sending state, plan, usage today and this month, and verified senders. Scope: `marketing:read`.","operationId":"get_businesses_business_marketing_overview","security":[{"bearer":["marketing:read"]}],"parameters":[{"name":"business","in":"path","required":true,"description":"The business id, from GET \/businesses.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application\/json":{"example":{"sending_enabled":true,"usage":{"contacts":1240,"sent_this_month":3800,"sent_today":0,"warmup_ceiling_today":800},"counts":{"lists":3,"campaigns":7}}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}}}},"\/businesses\/{business}\/marketing\/contacts":{"post":{"tags":["Email marketing"],"summary":"Add a contact","description":"Adds one contact. consent and consent_source are required: say where they agreed to hear from you. Scope: `marketing:write`.","operationId":"post_businesses_business_marketing_contacts","security":[{"bearer":["marketing:write"]}],"parameters":[{"name":"business","in":"path","required":true,"description":"The business id, from GET \/businesses.","schema":{"type":"integer"}}],"responses":{"201":{"description":"OK","content":{"application\/json":{"example":{"id":2210,"email":"sam@example.com","first_name":"Sam","last_name":null,"status":"subscribed","source":"api","fields":{"city":"Pune"}}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}},"requestBody":{"required":true,"content":{"application\/json":{"example":{"email":"sam@example.com","first_name":"Sam","lists":[4],"fields":{"city":"Pune"},"consent":true,"consent_source":"Checkout opt-in, 9 Nov 2026"}}}}}},"\/businesses\/{business}\/marketing\/campaigns":{"get":{"tags":["Email marketing"],"summary":"List campaigns","description":"Every campaign, with its state and stats. Scope: `marketing:read`.","operationId":"get_businesses_business_marketing_campaigns","security":[{"bearer":["marketing:read"]}],"parameters":[{"name":"business","in":"path","required":true,"description":"The business id, from GET \/businesses.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application\/json":{"example":[{"id":9,"name":"November roast","subject":"The November roast","status":"sent","recipients":1204,"sent":1180,"delivered":1171,"opens":512,"clicks":96,"bounces":9,"unsubscribes":4}]}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}}},"post":{"tags":["Email marketing"],"summary":"Create a campaign","description":"A draft. Check it, test it, then send it. Scope: `marketing:write`.","operationId":"post_businesses_business_marketing_campaigns","security":[{"bearer":["marketing:write"]}],"parameters":[{"name":"business","in":"path","required":true,"description":"The business id, from GET \/businesses.","schema":{"type":"integer"}}],"responses":{"201":{"description":"OK","content":{"application\/json":{"example":{"id":10,"name":"December roast","subject":"Winter blend is here","status":"draft","audience":{"lists":[4],"segments":[],"exclude_lists":[]},"next":"POST campaigns\/10\/check, then \/test, then \/send"}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}},"requestBody":{"required":true,"content":{"application\/json":{"example":{"name":"December roast","subject":"Winter blend is here","lists":[4],"html":"

Winter blend<\/h1>\u2026"}}}}}},"\/businesses\/{business}\/marketing\/campaigns\/{id}\/send":{"post":{"tags":["Email marketing"],"summary":"Send a campaign","description":"Queues it. Paced by the plan and the domain's warm-up. Scope: `marketing:write`.","operationId":"post_businesses_business_marketing_campaigns_id_send","security":[{"bearer":["marketing:write"]}],"parameters":[{"name":"business","in":"path","required":true,"description":"The business id, from GET \/businesses.","schema":{"type":"integer"}},{"name":"id","in":"path","required":true,"description":"The campaign id.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application\/json":{"example":{"id":10,"name":"December roast","status":"sending","message":"Sending now."}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}}}},"\/businesses\/{business}\/marketing\/send":{"post":{"tags":["Email marketing"],"summary":"Send one transactional email","description":"A single message to one person, tracked like a campaign. Scope: `marketing:write`.","operationId":"post_businesses_business_marketing_send","security":[{"bearer":["marketing:write"]}],"parameters":[{"name":"business","in":"path","required":true,"description":"The business id, from GET \/businesses.","schema":{"type":"integer"}}],"responses":{"202":{"description":"OK","content":{"application\/json":{"example":{"message_id":"k3j9x0q2m8w1v7c4b6n5z0a1","status":"queued"}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}},"requestBody":{"required":true,"content":{"application\/json":{"example":{"from":"orders@northwind.coffee","to":"sam@example.com","subject":"Your order shipped","html":"

On its way.<\/p>","type":"transactional"}}}}}},"\/businesses\/{business}\/tools":{"get":{"tags":["Tools"],"summary":"List tools","description":"Every tool this business may run, with its fields. Scope: `tools:read`.","operationId":"get_businesses_business_tools","security":[{"bearer":["tools:read"]}],"parameters":[{"name":"business","in":"path","required":true,"description":"The business id, from GET \/businesses.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application\/json":{"example":{"tools":[{"slug":"dns-lookup","name":"DNS lookup","category":"domains","what_it_does":"Every record for a hostname, from public resolvers.","fields":{"host":{"type":"text","required":true}}}]}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}}}},"\/businesses\/{business}\/tools\/history":{"get":{"tags":["Tools"],"summary":"Run history","description":"Recent runs, newest first. Scope: `tools:read`.","operationId":"get_businesses_business_tools_history","security":[{"bearer":["tools:read"]}],"parameters":[{"name":"business","in":"path","required":true,"description":"The business id, from GET \/businesses.","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Default 20.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application\/json":{"example":{"runs":[{"tool":"seo-audit","summary":"3 issues on \/","at":"2026-11-08T19:00:00Z"}]}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}}}},"\/businesses\/{business}\/tools\/{tool}":{"get":{"tags":["Tools"],"summary":"Get a tool","description":"One tool and its fields. Scope: `tools:read`.","operationId":"get_businesses_business_tools_tool","security":[{"bearer":["tools:read"]}],"parameters":[{"name":"business","in":"path","required":true,"description":"The business id, from GET \/businesses.","schema":{"type":"integer"}},{"name":"tool","in":"path","required":true,"description":"The tool slug.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application\/json":{"example":{"slug":"seo-audit","name":"SEO audit","fields":{"url":{"type":"url","required":true}}}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}}},"post":{"tags":["Tools"],"summary":"Run a tool","description":"The body is the tool's fields. Scope: `tools:run`.","operationId":"post_businesses_business_tools_tool","security":[{"bearer":["tools:run"]}],"parameters":[{"name":"business","in":"path","required":true,"description":"The business id, from GET \/businesses.","schema":{"type":"integer"}},{"name":"tool","in":"path","required":true,"description":"The tool slug.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application\/json":{"example":{"ok":true,"summary":"3 issues on \/","checks":[{"status":"warn","label":"Meta description","detail":"Missing on \/"}],"stats":{"words":412}}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}},"requestBody":{"required":true,"content":{"application\/json":{"example":{"url":"https:\/\/northwind.coffee\/"}}}}}},"\/businesses\/{business}\/council":{"post":{"tags":["AI council"],"summary":"Start a council turn","description":"approve \"safe\" (default) lets the council read and report only. \"auto\" lets it make changes within the business's permissions. Send the thread back to continue a conversation. Scope: `council:write`.","operationId":"post_businesses_business_council","security":[{"bearer":["council:write"]}],"parameters":[{"name":"business","in":"path","required":true,"description":"The business id, from GET \/businesses.","schema":{"type":"integer"}}],"responses":{"202":{"description":"OK","content":{"application\/json":{"example":{"ok":true,"message_id":5121,"thread":"9b1c2e7a-4f0d-4a52-9a6e-1f0d2c3b4a59","status":"running","poll":"\/api\/v1\/businesses\/60\/council\/messages\/5121"}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}},"requestBody":{"required":true,"content":{"application\/json":{"example":{"message":"Add a wholesale enquiry form to the contact page.","approve":"auto","thread":null}}}}}},"\/businesses\/{business}\/council\/messages\/{message}":{"get":{"tags":["AI council"],"summary":"Get a council reply","description":"status is running, complete or failed. body is the council's answer once complete. Scope: `council:read`.","operationId":"get_businesses_business_council_messages_message","security":[{"bearer":["council:read"]}],"parameters":[{"name":"business","in":"path","required":true,"description":"The business id, from GET \/businesses.","schema":{"type":"integer"}},{"name":"message","in":"path","required":true,"description":"The message_id from the start call.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application\/json":{"example":{"ok":true,"message":{"id":5121,"thread":"9b1c2e7a-\u2026","status":"complete","body":"Added a wholesale form to \/contact. It posts to orders@northwind.coffee\u2026","created_at":"2026-11-09T08:44:10Z","updated_at":"2026-11-09T08:46:52Z"}}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}}}},"\/businesses\/{business}\/council\/threads\/{thread}":{"get":{"tags":["AI council"],"summary":"Get a conversation","description":"Every message in one thread, oldest first. Scope: `council:read`.","operationId":"get_businesses_business_council_threads_thread","security":[{"bearer":["council:read"]}],"parameters":[{"name":"business","in":"path","required":true,"description":"The business id, from GET \/businesses.","schema":{"type":"integer"}},{"name":"thread","in":"path","required":true,"description":"The thread id.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application\/json":{"example":{"ok":true,"thread":"9b1c2e7a-\u2026","messages":[{"id":5120,"role":"user","who":"API \u00b7 Deploy bot","status":null,"body":"Add a wholesale enquiry form\u2026"},{"id":5121,"role":"assistant","who":"Full council","status":"complete","body":"Added a wholesale form\u2026"}]}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}}}},"\/businesses\/{business}\/browser":{"get":{"tags":["Browser"],"summary":"How to drive it","description":"The actions, and which sites it may open. Scope: `browser`.","operationId":"get_businesses_business_browser","security":[{"bearer":["browser"]}],"parameters":[{"name":"business","in":"path","required":true,"description":"The business id, from GET \/businesses.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"text\/plain":{"example":"POST this URL with do= and its fields. Answers are plain text.\nopen url= | look | click ref=N | type ref=N text=\u2026\nAllowed sites: northwind.coffee, shop.northwind.coffee"}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}}},"post":{"tags":["Browser"],"summary":"Act","description":"do is one of open, look, click, type, select, scroll, back, reload, read, find, wait. Scope: `browser`.","operationId":"post_businesses_business_browser","security":[{"bearer":["browser"]}],"parameters":[{"name":"business","in":"path","required":true,"description":"The business id, from GET \/businesses.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"text\/plain":{"example":"Contact \u00b7 Northwind Coffee \u2014 https:\/\/northwind.coffee\/contact\n[1] link \"Home\"\n[2] textbox \"Your email\"\n[3] button \"Send\""}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}},"requestBody":{"required":true,"content":{"application\/json":{"example":{"do":"open","url":"\/contact"}}}}}},"\/businesses\/{business}\/backups":{"get":{"tags":["Backups"],"summary":"List backups","description":"Every backup, and any requests waiting on you. Scope: `backups:read`.","operationId":"get_businesses_business_backups","security":[{"bearer":["backups:read"]}],"parameters":[{"name":"business","in":"path","required":true,"description":"The business id, from GET \/businesses.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application\/json":{"example":{"ok":true,"backups":[{"uuid":"3f1c\u2026","name":"Nightly","size_mb":812,"created_at":"2026-11-09T02:00:00Z"}],"requests":[]}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}}}},"\/businesses\/{business}\/backups\/requests":{"post":{"tags":["Backups"],"summary":"Request a backup","description":"action is create or delete. A delete needs backup (the uuid). Scope: `backups:write`.","operationId":"post_businesses_business_backups_requests","security":[{"bearer":["backups:write"]}],"parameters":[{"name":"business","in":"path","required":true,"description":"The business id, from GET \/businesses.","schema":{"type":"integer"}}],"responses":{"202":{"description":"OK","content":{"application\/json":{"example":{"ok":true,"request":{"id":14,"action":"create","status":"pending"}}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}},"requestBody":{"required":true,"content":{"application\/json":{"example":{"action":"create","reason":"Before the theme migration"}}}}}},"\/businesses\/{business}\/backups\/requests\/{id}":{"get":{"tags":["Backups"],"summary":"Get a request","description":"pending, approved, declined, done or failed. Scope: `backups:read`.","operationId":"get_businesses_business_backups_requests_id","security":[{"bearer":["backups:read"]}],"parameters":[{"name":"business","in":"path","required":true,"description":"The business id, from GET \/businesses.","schema":{"type":"integer"}},{"name":"id","in":"path","required":true,"description":"The request id.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application\/json":{"example":{"ok":true,"request":{"id":14,"action":"create","status":"done"}}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}}},"delete":{"tags":["Backups"],"summary":"Withdraw a request","description":"Only while it is still pending. Scope: `backups:write`.","operationId":"delete_businesses_business_backups_requests_id","security":[{"bearer":["backups:write"]}],"parameters":[{"name":"business","in":"path","required":true,"description":"The business id, from GET \/businesses.","schema":{"type":"integer"}},{"name":"id","in":"path","required":true,"description":"The request id.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application\/json":{"example":{"ok":true,"request":{"id":14,"status":"withdrawn"}}}}},"400":{"description":"The request could not be read. Send JSON with Content-Type: application\/json."},"401":{"description":"No key, a malformed key, or a revoked or expired one."},"403":{"description":"The key does not have the scope this endpoint needs. Also returned when the business's own Permissions page switches the action off (reason: permission)."},"404":{"description":"No such business, service or record on this account, or outside the key's businesses. We never confirm that something exists on another account."},"409":{"description":"The business is read-only, asleep, or has no running server (see reason)."},"422":{"description":"A field is missing or wrong. message says what, and errors lists each field."},"429":{"description":"Too many requests for this key this minute. Wait Retry-After seconds."},"502":{"description":"A server behind the business (the mail server, the container) did not answer properly. Safe to retry."}}}}}}