API reference

Keys

Create API keys under API & Keys. The key is shown once, right at creation, and starts with nc_live_ so you can spot it in logs. Keys currently have the same reach as the dashboard; scoped keys are on the roadmap.

Sending a request

Every endpoint lives under https://api.nairacloud.xyz. Send your key in the Authorization header:

Every response is JSON. Successes have success: true and data. Errors are objects with success: false, a machine-readable code and a plain-English message inside error, plus a requestId you can quote to support.

Lifecycle

• POST /v1/instances -- deploy (plan, os, key, name).
• GET /v1/instances -- list. Each server includes id, hostname, status, sshPort, plan, routes[], websiteUrl, and webOriginPort.
• POST /v1/instances/:id/start | /stop | /rebuild -- lifecycle. Rebuild keeps the same SSH port and site Hosts.
• DELETE /v1/instances/:id -- delete after confirmation.

Website & networking

• POST /v1/instances/:id/routes -- add a site (body: { "label": "api", "originPort": 3000 }). The response includes the NairaCloud hostname api-<hostname>.nairacloud.xyz and the sslip alias.
• PATCH /v1/instances/:id/routes/:label -- change that site's origin port.
• DELETE /v1/instances/:id/routes/:label -- remove a site (at least one must remain).
• PATCH /v1/instances/:id/web-origin -- alias for updating the default web site origin.
• POST /v1/instances/:id/domains -- attach a custom domain (optional routeLabel) after its A record points at the node IP.
• DELETE /v1/instances/:id/domains/:domain -- detach a custom domain.
• POST /v1/instances/:id/ports -- publish a raw TCP port (body: { "containerPort": 5432 }). The platform returns the allocated public hostPort.