API Reference

Everything you can do in the dashboard you can do with the API. Create projects, trigger deploys, manage nodes, rotate secrets — all with a single bearer token. Use it to build CI bots, Slack integrations, or whatever else fits your workflow.

All endpoints accept and return JSON. The base URL for the hosted service is https://api.nexos.dev/api.

Authentication

Nexos supports two authentication methods:

JWT Cookies

The web dashboard authenticates via GitHub OAuth and receives a JWT stored in an HTTP-only cookie. This is handled automatically when using the dashboard.

API Keys

For programmatic access, create an API key from Settings > API Keys in the dashboard. API keys are prefixed with nxs_ and sent via the Authorization header:

curl https://api.nexos.dev/api/projects \
  -H "Authorization: Bearer nxs_your_api_key_here"

API keys are hashed with bcrypt before storage. The plaintext key is shown only once at creation time. If you lose it, you must generate a new one.

Endpoints

Authentication

Method	Path	Description
`GET`	`/auth/github`	Redirect to GitHub OAuth flow
`GET`	`/auth/github/callback`	Handle GitHub OAuth callback
`GET`	`/auth/me`	Get current authenticated user
`POST`	`/auth/api-keys`	Create a new API key
`GET`	`/auth/api-keys`	List API keys (masked)
`DELETE`	`/auth/api-keys/:id`	Revoke an API key

Projects

Method	Path	Description
`GET`	`/projects`	List all projects
`POST`	`/projects`	Create a new project
`GET`	`/projects/:id`	Get project details
`PATCH`	`/projects/:id`	Update project settings
`DELETE`	`/projects/:id`	Delete a project and all environments

Deployments & Environments

Method	Path	Description
`GET`	`/projects/:id/environments`	List environments for a project
`GET`	`/environments/:id`	Get environment details
`POST`	`/environments/:id/rebuild`	Rebuild environment from the latest commit (alias: `/restart`)
`POST`	`/environments/:id/pause`	Stop every container; also stops shared Postgres/Redis when this is the last active environment
`POST`	`/environments/:id/resume`	Start previously-paused containers (no rebuild)
`POST`	`/environments/:id/reset`	Reset the environment's database to an empty state
`POST`	`/environments/:id/destroy`	Destroy environment
`GET`	`/deployments/:id`	Get deployment details
`GET`	`/deployments/:id/logs`	Get build logs

Environment Variables

Method	Path	Description
`GET`	`/projects/:id/env-vars`	List environment variables (masked values)
`PUT`	`/projects/:id/env-vars`	Create or update an environment variable
`DELETE`	`/projects/:id/env-vars/:varId`	Delete an environment variable

Nodes

Method	Path	Description
`GET`	`/nodes`	List registered nodes
`POST`	`/nodes/join-token`	Generate a node join token
`GET`	`/nodes/:id`	Get node details and status
`DELETE`	`/nodes/:id`	Remove a node from the network

Quotas

Method	Path	Description
`GET`	`/quota`	Get current resource usage and quota limits

Webhooks

Method	Path	Description
`POST`	`/webhooks/github`	GitHub webhook receiver (push and delete events)

Request and Response Examples

Create a Project

POST /api/projects
Content-Type: application/json
Authorization: Bearer nxs_your_api_key

{
  "name": "my-app",
  "github_repo": "octocat/my-app",
  "dockerfile": "Dockerfile",
  "build_context": ".",
  "services": {
    "postgres": true,
    "redis": true,
    "s3": false
  }
}

Response:

{
  "id": "proj_abc123",
  "name": "my-app",
  "slug": "my-app",
  "github_repo": "octocat/my-app",
  "dockerfile": "Dockerfile",
  "build_context": ".",
  "services": {
    "postgres": true,
    "redis": true,
    "s3": false
  },
  "created_at": "2026-04-10T12:00:00Z"
}

Get Quota Usage

GET /api/quota
Authorization: Bearer nxs_your_api_key

Response:

{
  "plan": "pro",
  "usage": {
    "projects": 12,
    "total_cpu": 14.5,
    "total_memory_mb": 29696,
    "build_minutes_used": 2340
  },
  "limits": {
    "max_projects": 25,
    "max_cpu": 64,
    "max_memory_mb": 131072,
    "build_minutes": 5000
  }
}