// Reference for all Nixopus API operations callable via nixopus_api(method, path, body)
| name | api-catalog |
| description | Reference for all Nixopus API operations callable via nixopus_api(method, path, body) |
[api-catalog]
Use nixopus_api({ method, path, body? }) for ALL Nixopus API calls below.
Pass the HTTP method, the full path (embed path params and query strings directly in the string), and an optional body object for POST/PUT/PATCH/DELETE payloads.
CALLING FORMAT:
method — one of: GET, POST, PUT, PATCH, DELETEpath — full API path with path params and query strings embedded as a stringbody — JSON object for request body (POST/PUT/PATCH/DELETE with payloads)EXAMPLES:
nixopus_api({ method: "GET", path: "/api/v1/deploy/applications?page=1&page_size=10" })
nixopus_api({ method: "GET", path: "/api/v1/deploy/application?id=APP_UUID" })
nixopus_api({ method: "GET", path: "/api/v1/deploy/application/deployments?id=APP_UUID&limit=5" })
nixopus_api({ method: "GET", path: "/api/v1/deploy/application/deployments/DEPLOY_UUID" })
nixopus_api({ method: "GET", path: "/api/v1/deploy/application/deployments/DEPLOY_UUID/logs?page=1&page_size=50" })
nixopus_api({ method: "POST", path: "/api/v1/deploy/application/restart", body: { id: "DEPLOY_UUID" } })
nixopus_api({ method: "POST", path: "/api/v1/deploy/application/redeploy", body: { id: "APP_UUID" } })
nixopus_api({ method: "GET", path: "/api/v1/machines/stats" })
nixopus_api({ method: "POST", path: "/api/v1/notification/send", body: { channel: "slack", message: "deploy done" } })
COMMON MISTAKES TO AVOID:
operation or params fields — the tool does not accept thoseapplication_id as the query param for deployments — use iddeploy_on_create in any request body — it is an unknown field and the API rejects the entire request with HTTP 400.environment from POST /api/v1/deploy/application — it is required. Valid values: production, staging, development.build_pack from POST /api/v1/deploy/application — it is required. Valid values: dockerfile, nixpacks, static.port from POST /api/v1/deploy/application — it is required (1–65535).source: "github_public" — it is not a valid value and will be rejected.source valid values: github (default — requires connector), public_git (any public HTTPS URL), s3, zip, template.repository format depends on source:
source: "github" (or omitted) → numeric GitHub connector repo ID. Call GET /api/v1/github-connector/repositories, use the integer id. NEVER pass owner/repo slug.source: "public_git" → full HTTPS git URL, e.g. "https://github.com/nixopus/sample-app.git". Use this when the repo is NOT in the GitHub connector.get_application_deployments → GET /api/v1/deploy/application/deployments?id=APP_UUID (NOT ?application_id=)get_deployment_by_id → GET /api/v1/deploy/application/deployments/DEPLOY_UUID (path param, NOT query)restart_deployment → POST /api/v1/deploy/application/restart with body: { id: "DEPLOY_UUID" }GET /api/v1/container/CONTAINER_ID (NOT ?id=)REQUIRED FLOW FOR DEPLOYMENT:
GET /api/v1/github-connector/repositories
source: "github", repository: <numeric_id>source: "public_git", repository: "https://github.com/org/repo.git"POST /api/v1/deploy/application/project with { name, repository, source, branch, ... }POST /api/v1/deploy/application/project/deploy with { id: <project_uuid> }GET /api/v1/deploy/application/deployments?id=<project_uuid> until status is success/failedGET /api/v1/deploy/applications — List apps. Query: page?, page_size?, sort_by?, sort_direction?
GET /api/v1/deploy/application?id={app_uuid} — Get one app by UUID
GET /api/v1/deploy/application/deployments?id={app_uuid} — List deployments. ⚠ param is id NOT application_id. Query: page?, limit?
GET /api/v1/deploy/application/deployments/{deployment_id} — Get deployment by UUID (path param, NOT query string)
GET /api/v1/deploy/application/deployments/{deployment_id}/logs — Deployment logs. Query: page?, page_size?, level?, start_time?, end_time?, search_term?
GET /api/v1/deploy/application/logs/{application_id} — App-wide logs (path param)
POST /api/v1/deploy/application — Create app. Body: { repository (INTEGER numeric GitHub repo ID — NOT "owner/repo"), name?, branch?, port?, build_pack?, dockerfile_path?, base_path?, environment_variables?, domains? }
PUT /api/v1/deploy/application — Update app config. Body: { id, ...fields }
DELETE /api/v1/deploy/application — Delete app. Body: { id }
POST /api/v1/deploy/application/redeploy — Rebuild & redeploy. Body: { id (app UUID), force?, force_without_cache? }
POST /api/v1/deploy/application/restart — Restart deployment (no rebuild). Body: { id (deployment UUID) }
POST /api/v1/deploy/application/rollback — Rollback. Body: { id (app UUID) }
POST /api/v1/deploy/application/cancel-deployment — Cancel in-flight. Body: { deployment_id }
POST /api/v1/deploy/application/recover — Recover. Body: { application_id? } (omit to recover all)
PUT /api/v1/deploy/application/labels?id={app_uuid} — Update labels. Body: (labels payload)
POST /api/v1/deploy/application/domains?id={app_uuid} — Add domain. Body: { domain, service_name?, port? }
DELETE /api/v1/deploy/application/domains?id={app_uuid} — Remove domain. Body: { domain }
GET /api/v1/deploy/application/compose-services?id={app_uuid} — List compose services
GET /api/v1/deploy/application/servers?id={app_uuid} — Get server assignment
PUT /api/v1/deploy/application/servers — Set servers. Body: { application_id, server_ids, primary_server_id?, routing_strategy? }
POST /api/v1/deploy/application/project — Create project. Body: { name, repository (INTEGER numeric GitHub repo ID — NOT "owner/repo"), branch?, build_pack?, port?, environment?, ... } POST /api/v1/deploy/application/project/deploy — Deploy project. Body: { id } GET /api/v1/deploy/application/project/family?family_id={id} — Get project family GET /api/v1/deploy/application/project/family/environments?family_id={id} — List family environments POST /api/v1/deploy/application/project/add-to-family — Add project to family
GET /api/v1/deploy/artifacts?application_id={app_uuid} — List artifacts for app (⚠ this one uses application_id)
GET /api/v1/deploy/artifacts/{deployment_id}/download — Download URL (path param)
DELETE /api/v1/deploy/artifacts/{deployment_id} — Delete artifact (path param)
GET /api/v1/domain — List domains. Query: type? GET /api/v1/domain/generate — Generate random subdomain POST /api/v1/domain/custom — Add custom domain DELETE /api/v1/domain/custom — Remove custom domain POST /api/v1/domain/verify — Verify domain GET /api/v1/domain/dns-check?id={custom_domain_id} — DNS check
POST /api/v1/github-connector — Create connector. Body: { app_id, client_id, client_secret, pem, slug, webhook_secret } PUT /api/v1/github-connector — Update connector. Body: { connector_id, installation_id } DELETE /api/v1/github-connector — Delete connector. Body: { id } GET /api/v1/github-connector/all — List connectors GET /api/v1/github-connector/repositories — List GitHub repos POST /api/v1/github-connector/repository/branches — List branches. Body: { repository_name }
GET /api/v1/container — List containers. Query: page?, page_size?, status?, search? GET /api/v1/container/{container_id} — Get container (path param) POST /api/v1/container/{container_id}/logs — Logs (path param). Body: { id, follow?, tail?, since?, until? } POST /api/v1/container/{container_id}/start — Start (path param) POST /api/v1/container/{container_id}/stop — Stop (path param) POST /api/v1/container/{container_id}/restart — Restart (path param) DELETE /api/v1/container/{container_id} — Remove (path param) PUT /api/v1/container/{container_id}/resources — Update resources. Body: { cpu_shares?, memory?, memory_swap? } POST /api/v1/container/images — List images. Body: { all?, container_id?, image_prefix? }
GET /api/v1/machines — List servers. Query: page?, page_size?, search? GET /api/v1/machines/stats — Host stats (CPU/RAM/disk/network) — no params POST /api/v1/machines/exec — ⚠ Run command on host. Body: { command } GET /api/v1/machines/ssh/status — SSH status for all machines GET /api/v1/machines/{id}/ssh/status — SSH status for one machine (path param) PUT /api/v1/machines/{id}/set-default — Set as org default (path param) GET /api/v1/machines/status — Lifecycle status POST /api/v1/machines/restart — ⚠ Restart machine POST /api/v1/machines/pause — ⚠ Pause machine POST /api/v1/machines/resume — ⚠ Resume machine GET /api/v1/machines/metrics — Time-series metrics. Query: from, to, limit GET /api/v1/machines/metrics/summary — Summarized metrics. Query: from, to GET /api/v1/machines/events — Lifecycle events. Query: from, to, limit GET /api/v1/machines/backup/schedule — Get backup schedule PUT /api/v1/machines/backup/schedule — Update backup schedule GET /api/v1/machines/backups — List backups POST /api/v1/machines/backup — ⚠ Trigger backup
GET /api/v1/health — Health check (no auth) GET /api/v1/update/check — Check for updates POST /api/v1/update — ⚠ Trigger update GET /api/v1/audit/logs — Audit logs. Query: page?, page_size?, search?, resource_type? GET /api/v1/feature-flags — List feature flags GET /api/v1/feature-flags/check?feature_name={name} — Check one flag PUT /api/v1/feature-flags — ⚠ Update feature flag
GET /api/v1/mcp/catalog — List MCP provider catalog GET /api/v1/mcp/servers — List org MCP servers POST /api/v1/mcp/servers — Add MCP server PUT /api/v1/mcp/servers/{id} — Update MCP server (path param) DELETE /api/v1/mcp/servers — ⚠ Delete MCP server. Body: { id } POST /api/v1/mcp/servers/test — Test connection GET /api/v1/mcp/internal/tools — Discover MCP tools GET /api/v1/mcp/internal/servers — List enabled servers POST /api/v1/mcp/internal/tools/call — Call MCP tool. Body: { server_id, tool_name, arguments? }
POST /api/v1/notification/send — Send notification. Body: { channel (slack|discord|email), message, subject?, to?, metadata? } GET /api/v1/notification/preferences — Get preferences PATCH /api/v1/notification/preferences — Update preferences GET /api/v1/notification/smtp?id={org_id} — Get SMTP config POST /api/v1/notification/smtp — Create SMTP config PUT /api/v1/notification/smtp — Update SMTP config DELETE /api/v1/notification/smtp — Delete SMTP config GET /api/v1/notification/webhook/{type} — Get webhook (path param) POST /api/v1/notification/webhook — Create webhook PUT /api/v1/notification/webhook — Update webhook DELETE /api/v1/notification/webhook — Delete webhook
POST /api/v1/healthcheck — Create health check GET /api/v1/healthcheck?application_id={app_uuid} — Get health checks for app PUT /api/v1/healthcheck — Update health check DELETE /api/v1/healthcheck?application_id={app_uuid} — Delete for app PATCH /api/v1/healthcheck/toggle — Toggle health check GET /api/v1/healthcheck/results?application_id={app_uuid} — Results. Query: limit?, start_time?, end_time? GET /api/v1/healthcheck/stats?application_id={app_uuid} — Stats. Query: period?
GET /api/v1/extensions — List extensions. Query: category?, search?, type?, sort_by?, page?, page_size? GET /api/v1/extensions/categories — List categories GET /api/v1/extensions/{id} — Get extension by ID (path param) GET /api/v1/extensions/by-extension-id/{extension_id} — Get by extension ID (path param) [/api-catalog]
These fields have validate:"required" and WILL cause HTTP 400 if omitted.
name (string): Application namerepository (string): Numeric GitHub repository ID (get from GET /github-connector/repositories). → MUST be numeric GitHub repo ID — call GET /api/v1/github-connector/repositories and use the integer id. NEVER pass owner/repo slug or a URL.deployment_id (uuid.UUID): Deployment ID to cancelname (string): Application nameenvironment (shared_types.Environment): Deployment environment → Valid values: "production", "staging", "development"build_pack (shared_types.BuildPack): Build strategy for the application → Valid values: "dockerfile", "nixpacks", "static"repository (string): Numeric GitHub repository ID (get from GET /github-connector/repositories). Do NOT pass owner/repo slug — it will fail at parse time. → MUST be numeric GitHub repo ID — call GET /api/v1/github-connector/repositories and use the integer id. NEVER pass owner/repo slug or a URL.branch (string): Git branch to deployport (int): Port the application listens onname (string): Project namerepository (string): Numeric GitHub repository ID (get from GET /github-connector/repositories). Do NOT pass owner/repo slug — it will fail at parse time. → MUST be numeric GitHub repo ID — call GET /api/v1/github-connector/repositories and use the integer id. NEVER pass owner/repo slug or a URL.template_id (string): Template ID to deploy fromname (string): Name for the deployed applicationid (uuid.UUID): Application ID to deleteid (uuid.UUID): Project ID to deploysource_project_id (uuid.UUID): ID of the project to duplicateenvironment (shared_types.Environment): Environment for the duplicated project → Valid values: "production", "staging", "development"family_id (uuid.UUID): Project family IDdomain (string): Domain to check for availabilitydomain (string): Domain to validatename (string): Application name to check for uniquenessport (int): Port number to check for availabilityrepository (string): Numeric GitHub repository ID (get from GET /github-connector/repositories). → MUST be numeric GitHub repo ID — call GET /api/v1/github-connector/repositories and use the integer id. NEVER pass owner/repo slug or a URL.branch (string): Git branch to previewid (uuid.UUID): Application ID to redeployid (uuid.UUID): Application ID to restartid (uuid.UUID): Application ID to roll backapplication_id (uuid.UUID): Application ID to assign servers toserver_ids ([]uuid.UUID): Server IDs to assign to the applicationGenerate Caddyfile configurations for static sites and reverse proxies — SPA fallback routing, cache headers, compression, redirects, and error pages. Use when deploying a static site that needs custom Caddy configuration, or when the user needs SPA routing, caching, or redirect rules.
Generate docker-compose.yml for multi-service setups including databases, caches, and service dependencies. Use when the app needs a database, cache, message broker, or has multiple independently deployable services.
Size container memory and CPU limits, diagnose OOM kills and CPU throttling, and recommend resource adjustments by ecosystem. Use when containers are being OOM-killed, running slowly, or when setting initial resource limits for a deployment.
Build and deploy C/C++ applications — CMake, Meson, Ninja, and Dockerfile patterns. Use when deploying a C or C++ project, or when CMakeLists.txt or meson.build is detected.
Run database migrations safely during deployment — framework-specific commands, pre-deploy vs post-deploy timing, health gates, and rollback strategies. Use when the app has a database migration system and needs migrations run during deployment.
Build and deploy Deno applications — version detection, dependency caching, and Dockerfile patterns. Use when deploying a Deno project, or when deno.json or deno.jsonc is detected.