REST API
The Netkeel REST API lets a script, a CI pipeline or another tool work with your account over HTTPS. It can list your servers and applications, take and restore backups, start a Git deployment, follow background jobs and more.
The API uses the same access tokens as AI assistants (MCP), and the same rules: a token can only read until you allow changes. Changes that take applications offline, cannot be undone, run your own commands or cost money also need a confirmation step: the first request only shows what would happen, and a second request with a confirmation code makes the change. See Confirm a change.
Only the account owner and super admins can create tokens and turn changes on.
Create a token
Section titled “Create a token”- In the sidebar, open Integrations, then API & MCP.
- Click Create token.
- Give it a Name, such as “Deploy pipeline”.
- Under What it can do, keep Read only, or choose Read and change (see Let a token make changes).
- Choose when it Expires: 30 days, 90 days or 1 year. A Read only token can also have no expiry. A Read and change token always expires, after a year at most.
- Enter Your password. If you have two-factor authentication on, enter an Authenticator code too.
- Click Create token.
- Copy the token now. It starts with
nkm_and is shown only once.
The page shows the address of the API under REST API, for example https://my.netkeel.com/api/v1, and a ready-made curl command with your new token filled in.
Make your first request
Section titled “Make your first request”Send the token in the Authorization header of every request:
curl -H "Authorization: Bearer nkm_YOUR_TOKEN" https://my.netkeel.com/api/v1/serversReplace my.netkeel.com with the address shown on the page, and nkm_YOUR_TOKEN with your token. Answers are JSON. A single item comes back as { "data": { ... } }, and a list as:
{ "data": [ { "id": "...", "name": "web-1", "status": "ready" } ], "pagination": { "page": 1, "perPage": 50, "total": 1, "hasMore": false }}Lists take ?page= (from 1) and ?per_page= (default 50, up to 100). A few lists page in fixed steps instead: GET /applications and the backup lists always return 100 a page, and GET /activity takes per_page up to 50 (default 25).
The full description of every endpoint, in OpenAPI 3 format, is at https://my.netkeel.com/api/v1/openapi.json (use your own address). It needs no token, and you can load it into Postman, Insomnia or a code generator.
The examples on this page use these shell variables. They also use jq to read values out of the answers.
TOKEN=nkm_YOUR_TOKENAPI=https://my.netkeel.com/api/v1APP=your-application-id # from GET /applicationsWhat you can do
Section titled “What you can do”“Confirm” in this table means the endpoint needs the confirmation step.
| Endpoint | What it does |
|---|---|
GET /servers, GET /servers/{server_id} |
List your servers, or get one, with status, resources and the applications each hosts. |
GET /servers/{server_id}/uptime, GET /servers/{server_id}/firewall |
A server’s uptime and outages (?days=7, 30 or 90; any other value is refused with invalid_argument), and its firewall rules. |
GET /server-options |
The providers, locations, sizes and prices you can order, and whether you can order a server now. |
POST /servers |
Order a server. Confirm. See Order a server. |
DELETE /servers/{server_id} |
Delete a server. Confirm. Refused while it still hosts applications. The off-site copies of the applications that were on it stay under Backups › Deleted for 14 days after each application was deleted. |
POST /servers/{server_id}/reboot |
Reboot a server. Confirm. |
POST /servers/{server_id}/services/restart |
Restart a server’s services (service to restart only one). Confirm. |
GET /applications, GET /applications/{application_id} |
List your applications, or get one. |
GET /applications/{application_id}/logs |
The latest lines of a log (source, max_lines up to 200). |
GET /applications/{application_id}/domains, .../settings, .../uptime |
Domains and DNS, hosting settings (with cron jobs and redirects), uptime. |
POST /applications |
Install an application on a server (server_id, domain, application_type). Confirm. |
DELETE /applications/{application_id} |
Delete an application. Confirm. |
PUT /applications/{application_id}/status |
Disable or enable an application (status: disabled or active). Confirm. |
GET /applications/{application_id}/deployments |
Git deploy settings and recent deployments. |
POST /applications/{application_id}/deployments |
Start a Git deployment. Confirm. |
POST /applications/{application_id}/staging |
Create a staging copy. |
POST .../staging/push, POST .../staging/pull |
Put staging over live, or live over staging. Confirm. |
PUT .../php-version |
Switch PHP (version). Confirm. |
POST .../cache/purge, POST .../php/restart |
Clear the caches, restart PHP. |
POST /applications/{application_id}/cron-jobs |
Add a cron job (schedule, command: one line of up to 700 characters). Confirm. |
DELETE /applications/{application_id}/cron-jobs/{line_number}?command=... |
Remove a cron job. See Remove a cron job or a redirect. |
POST /applications/{application_id}/redirects |
Add a redirect (source, destination, status 301 or 302). Confirm. |
DELETE /applications/{application_id}/redirects/{line_number}?source=... |
Remove a redirect. |
GET /backups, GET /applications/{application_id}/backups |
Backups of all applications, or of one. |
POST /applications/{application_id}/backups |
Take a backup now (description). |
POST .../backups/{backup_id}/restore |
Restore a backup (files, database, both on by default). Confirm. |
DELETE .../backups/{backup_id} |
Delete a backup. Confirm. |
GET /jobs, GET /jobs/{job_id} |
Background jobs (the newest 100), or one job and its status. |
GET /alerts, DELETE /alerts/{alert_key} |
Open alerts, or dismiss one. |
GET /activity, GET /notification-channels |
The activity log and your notification channels. |
The API cannot reach billing, payment methods, team members, your account or security settings, tokens, databases, files, SSH keys or the credentials of your integrations. Passwords and keys are left out of every answer.
Let a token make changes
Section titled “Let a token make changes”Changes are off until you turn them on. Two things must both be true:
- Allow tokens to make changes is on for the account.
- The token was made with Read and change.
To turn changes on:
- In the sidebar, open Integrations, then API & MCP.
- Switch on Allow tokens to make changes.
- Enter Your password, and an Authenticator code if you have two-factor authentication on, then confirm.
- Create a token and choose Read and change.
To go back to read-only, switch Allow tokens to make changes off. Every token becomes read-only straight away. The same switch applies to AI assistants.
Every change is recorded in your account’s Activity under the token’s name, for example API token "Deploy pipeline".
Take a backup
Section titled “Take a backup”curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \ -d '{"description":"Before release"}' "$API/applications/$APP/backups"Work that runs in the background answers 202 with a job. Follow it with GET /jobs/{job_id}:
curl -H "Authorization: Bearer $TOKEN" "$API/jobs/JOB_ID"If a change takes longer than the API waits, the answer is also 202, with "pending": true and a message, instead of an error. The change may still be applied, so check the result (for example with GET /jobs) before you send it again.
Confirm a change
Section titled “Confirm a change”These changes never run on the first request:
- They take applications offline for a while: rebooting a server, restarting its services, disabling or enabling an application, and starting a Git deployment.
- They cannot be undone, or they run your own commands: deleting a server, an application or a backup, restoring a backup, putting staging live (or live over staging), and adding a cron job or a redirect.
- They cost money: ordering a server and installing an application.
Each takes two requests:
- Preview. Send the request without
confirm. Nothing changes. The answer is409with the codeconfirmation_required, a description of what would happen, and a confirmation code inerror.details.preview.confirmationCode. - Confirm. Send exactly the same request again, with
confirmset totrueandconfirmation_codeset to that code. ForPOSTandPUTthey go in the JSON body. ForDELETEthey go in the query:?confirm=true&confirmation_code=....
A preview answer looks like this:
{ "error": { "code": "confirmation_required", "message": "Nothing was changed. This would delete backup ... Send the same request again with confirm: true and confirmation_code: \"7K2QM-X9D4R-0HV3T-PZ8NB\" to go ahead (the code works once, for 10 minutes).", "details": { "preview": { "operation": "delete_backup", "risk": "destructive", "summary": "This would delete backup ...", "warning": "...", "target": { "kind": "application", "id": "...", "label": "example.com" }, "confirmationCode": "7K2QM-X9D4R-0HV3T-PZ8NB", "confirmationExpiresAt": "2026-11-15T10:20:00.000Z" } } }}A code works once, for 10 minutes, and only for the same token, the same endpoint and the same values. Sending confirm: true without a code, or with a code that is spent, expired or was made for other values, answers 409 with the code confirmation_invalid and changes nothing. Ask for a new preview then.
Delete a backup
Section titled “Delete a backup”BACKUP=your-backup-id # from GET /applications/$APP/backups
# 1. Preview: nothing is deleted.CODE=$(curl -s -X DELETE -H "Authorization: Bearer $TOKEN" \ "$API/applications/$APP/backups/$BACKUP" | jq -r .error.details.preview.confirmationCode)
# 2. Delete for real.curl -X DELETE -H "Authorization: Bearer $TOKEN" \ "$API/applications/$APP/backups/$BACKUP?confirm=true&confirmation_code=$CODE"Restore a backup
Section titled “Restore a backup”# 1. Preview: nothing is restored.CODE=$(curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \ -d '{}' "$API/applications/$APP/backups/$BACKUP/restore" | jq -r .error.details.preview.confirmationCode)
# 2. Restore for real: the same values, plus confirm and the code.curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \ -d "{\"confirm\":true,\"confirmation_code\":\"$CODE\"}" "$API/applications/$APP/backups/$BACKUP/restore"Start a Git deployment
Section titled “Start a Git deployment”# 1. Preview: nothing is deployed.CODE=$(curl -s -X POST -H "Authorization: Bearer $TOKEN" \ "$API/applications/$APP/deployments" | jq -r .error.details.preview.confirmationCode)
# 2. Deploy.curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \ -d "{\"confirm\":true,\"confirmation_code\":\"$CODE\"}" "$API/applications/$APP/deployments"A pipeline that deploys on every push runs both steps one after the other. The deployment then answers 202 with a job to follow.
Order a server
Section titled “Order a server”POST /servers needs the price of the size you order, exactly as GET /server-options gives it, so you never pay a price you have not seen:
monthly_priceandhourly_price: themonthlyandhourlyvalues of the size’s entry inproviders[].serverTypes[].prices[]whoselocationis the location you order. Send them as strings, such as"10.5"and"0.0144": the same digits as in the answer, in quotes (jq’stostringdoes this).currency: the size’scurrency, or the provider’s when the size has none.
If the price changed since you read it, the answer is 409 with “Pricing changed” and nothing is ordered. Read the options again.
PROVIDER=vultr; LOCATION=fra; SIZE=vc2-1c-2gb # ids from GET /server-options
# The size's price at that location, straight from the options.PRICE=$(curl -s -H "Authorization: Bearer $TOKEN" "$API/server-options" | jq -c \ --arg p "$PROVIDER" --arg l "$LOCATION" --arg s "$SIZE" \ '.data.providers[] | select(.id == $p) as $provider | $provider.serverTypes[] | select(.id == $s) as $size | $size.prices[] | select(.location == $l) | {monthly_price: (.monthly | tostring), hourly_price: (.hourly | tostring), currency: ($size.currency // $provider.currency)}')
BODY=$(jq -c -n --argjson price "$PRICE" --arg p "$PROVIDER" --arg l "$LOCATION" --arg s "$SIZE" \ '{name: "web-2", provider: $p, location: $l, size: $s, stack_id: "wordpress", application_type: "wordpress", web_server: "nginx"} + $price')
# 1. Preview: nothing is ordered.CODE=$(curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \ -d "$BODY" "$API/servers" | jq -r .error.details.preview.confirmationCode)
# 2. Order it.curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \ -d "$(echo "$BODY" | jq -c --arg code "$CODE" '. + {confirm: true, confirmation_code: $code}')" "$API/servers"stack_id, application_type and web_server come from the stacks list of GET /server-options. The server is billed by the hour from the moment it starts. Your usual limits still apply: your plan, your server limits and your spending budget.
Remove a cron job or a redirect
Section titled “Remove a cron job or a redirect”Removing a cron job or a redirect needs no confirmation, but it needs two values that you read from GET /applications/{application_id}/settings first:
- the entry’s
lineNumber, in the path; - for a cron job, its exact
command, and for a redirect, its exact source path (slugin the settings), in the query. Encode it for a URL, as--data-urlencodedoes below.
curl -H "Authorization: Bearer $TOKEN" "$API/applications/$APP/settings" | jq '.data.cronJobs, .data.redirects'
# Remove the cron job on line 3.curl -X DELETE -G -H "Authorization: Bearer $TOKEN" \ --data-urlencode "command=php artisan schedule:run" "$API/applications/$APP/cron-jobs/3"
# Remove the redirect on line 0.curl -X DELETE -G -H "Authorization: Bearer $TOKEN" \ --data-urlencode "source=/old-page" "$API/applications/$APP/redirects/0"If the list changed since you read it, so that the line no longer holds that command or path, the removal is refused instead of removing the wrong entry.
Retry safely
Section titled “Retry safely”Installing an application, taking a backup, adding a cron job and adding a redirect take an optional request_id: a value you choose for that one change, 8 to 64 letters, digits, - or _. If a request fails or times out and you send it again within an hour with the same request_id and the same values, Netkeel answers with the first attempt instead of making the change twice. A retry may send the same confirmation code again.
Use a new request_id for each different change, and never send one again with other values.
CRON='{"schedule":"*/15 * * * *","command":"php artisan schedule:run","request_id":"release-42-cron"}'
# 1. Preview.CODE=$(curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \ -d "$CRON" "$API/applications/$APP/cron-jobs" | jq -r .error.details.preview.confirmationCode)
# 2. Add it. If this request fails or times out, send exactly the same request again.curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \ -d "$(echo "$CRON" | jq -c --arg code "$CODE" '. + {confirm: true, confirmation_code: $code}')" \ "$API/applications/$APP/cron-jobs"Errors
Section titled “Errors”Errors come back with an HTTP status and the same shape:
{ "error": { "code": "read_only", "message": "This access token can only read. ..." } }An error has details only when there is more to say: the preview of a change that needs confirming, or a reason code when Netkeel refused a change for a reason of its own (for example billing_no_card).
| Status | Code | Meaning |
|---|---|---|
400 |
invalid_argument, invalid_json, invalid_request, refused |
A value is missing, unknown or not valid, the body is not valid JSON, or Netkeel refused the change. The message says why. |
401 |
unauthorized |
The token is missing, wrong, expired or revoked. |
402 |
refused |
The change was refused for a billing reason, such as no payment card. details.reason says which. |
403 |
read_only, forbidden, workspace_unavailable, browser_origin |
The token or the account does not allow changes, the feature is off for your account, the account is suspended or has Integrations off, or the request came from a web page. |
404 |
not_found |
Unknown endpoint, or not found in your account. |
405 |
method_not_allowed |
The endpoint exists, but not with this method. The Allow header lists the methods it takes. |
409 |
confirmation_required |
A preview: nothing changed. See Confirm a change. |
409 |
confirmation_invalid |
confirm: true without a valid confirmation code. Nothing changed. |
409, 422 |
refused |
Netkeel refused the request, for example “Pricing changed”. The message says why. |
413 |
payload_too_large |
The body is larger than 64 KB. |
429 |
rate_limited |
Over a limit. Wait for the number of seconds in Retry-After, the seconds left in that limit’s minute, and try again. |
500 |
internal |
Something went wrong on our side. Try again later. |
502 |
unavailable |
Netkeel could not do it right now. Check the activity log before you try again. |
503 |
unavailable |
A state that passes, such as the server’s agent being offline or busy. Try again after Retry-After seconds (30). |
A 202 answer is never an error: the work was accepted and is running, or still running when the API stopped waiting.
Limits
Section titled “Limits”| Limit | Per minute |
|---|---|
| Requests per token | 120 |
| Endpoint calls per token | 60 |
| Changes per token | 20 |
| Endpoint calls per account, over all its tokens | 150 |
| Changes per account, over all its tokens | 40 |
| Failed token checks from one address | 20 |
Previews do not count as changes. These limits are shared with any AI assistant that uses the same tokens. Over a limit, the answer is 429, and Retry-After gives the seconds left in that limit’s minute.
Manage tokens
Section titled “Manage tokens”The Access tokens table lists each token’s name, its first characters, what it can do, when it was created, when it was last used and when it expires. An account can have up to 10 active tokens.
To stop a script, click Revoke next to its token and confirm. It loses access straight away. Use one token for each script, pipeline or computer, so you can revoke one without affecting the others.