API Reference

The CLI and external automation use the same authenticated API:

https://nept.cloud/api/v1

Authentication

Create a token in account settings or run nept login, then send it as a Bearer token:

curl https://nept.cloud/api/v1/me \
  -H "Authorization: Bearer $NEPT_API_KEY"

Tokens are scoped to their Nept user. Team roles are enforced consistently: viewers can read, members can change project resources, and admins/owners can perform administrative actions. Secret environment values require write access.

AI API keys are separate from general Nept API tokens. Create one at /ai/keys; its full nept_ai_... secret is shown once and can only call AI endpoints. General Nept tokens cannot call the AI API, and AI keys cannot access projects, deployments, databases, or account endpoints.

AI chat completions

Send a text-only, OpenAI-shaped request to an available model:

curl https://nept.cloud/api/v1/ai/chat/completions \
  -H "Authorization: Bearer $NEPT_AI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nept/deepseek-v4-pro",
    "messages": [{"role": "user", "content": "Hello"}],
    "max_tokens": 2048
  }'

The response includes standard choices and token usage, plus nept.creditsCharged and the remaining credit balance. Streaming, attachments, system messages, and tool calls are not supported on this endpoint yet.

Each AI key has a configurable 1–600 requests-per-minute limit. Responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset; throttled requests also include Retry-After. The /ai/keys page shows each key's request count, input/output tokens, and credits consumed.

Resources

| Area | Endpoints | | --- | --- | | Account | GET /me | | Projects | GET /projects, GET/PATCH/DELETE /projects/:id, PUT /projects/:id/team | | Environment | GET/PUT /projects/:id/env, POST /projects/:id/restart, POST /projects/:id/disconnect-git | | Domains | GET/POST /projects/:id/domains, DELETE /projects/:id/domains/:domainId, POST .../primary, POST .../connect | | Runtime | GET /projects/:id/pods, DELETE /projects/:id/pods/:pod, POST /projects/:id/exec, GET /projects/:id/logs, GET /projects/:id/logs/tail | | Deployments | GET/POST /deployments, GET /deployments/:id, POST /deployments/:id/redeploy, GET /deployments/:id/logs, GET /deployments/:id/logs/tail | | Databases | GET/POST /databases, GET/DELETE /databases/:id, GET /databases/:id/schema, POST /databases/:id/query, POST /databases/:id/query/generate | | Teams | GET/POST /teams, GET /teams/:id, invitations, member roles/removal, and invitation acceptance | | Usage and billing | GET /usage/balance, GET /usage/current, GET /usage/history, POST /billing/plan, POST /billing/credits | | Observability | GET /metrics, GET /analytics/traffic | | GitHub | GET /github/repos, repository commits/config detection, and POST /github/forks | | API tokens | GET/POST /tokens, DELETE /tokens/:id |

Log-tail endpoints return Server-Sent Events. Checkout endpoints return a secure provider URL; payment approval remains in the browser.

Deploying source

POST /deployments accepts either a GitHub repository or a base64 ZIP uploaded by the CLI:

{
  "kind": "source",
  "projectName": "my-app",
  "fullRepoName": "owner/repository",
  "branch": "main",
  "commit": "latest",
  "selectedFramework": "Next.js",
  "buildCommand": ["bun install --frozen-lockfile", "bun run build"],
  "runCommand": "bun run start",
  "outputDirectory": ".next",
  "rootDirectory": ".",
  "port": 3000,
  "envVars": {}
}

For a container deployment, use kind: "docker" with dockerImage, dockerTag, projectName, port, and optional resource/volume settings.

Errors and limits

Errors use a stable envelope:

{
  "error": {
    "code": "PROJECT_NOT_FOUND",
    "message": "Project not found"
  }
}

API keys are limited to 600 requests per minute. Large archives, SQL results, log queries, and third-party responses have additional size and timeout limits. Destructive CLI commands require --yes.