REST API

Everything the OpsNexus web app does goes through the same REST API. You can call it from scripts, CI jobs and other tools with an API key.

#Base URL and live reference

All endpoints live under /api on the address people use to open OpsNexus (PUBLIC_URL), for example https://opsnexus.example.com/api.

Your own server also serves an always up-to-date reference generated from the code:

#Authentication

Every endpoint needs a signed-in caller unless the tables below say otherwise. There are two ways to authenticate.

#Bearer access token

Sign in with POST /api/auth/login. The body takes identifier (email or username) and password, plus account_id for Account ID sign-in.

curl -s https://opsnexus.example.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"identifier": "admin@example.com", "password": "..."}'

The response has one of two shapes:

• {"tokens": {"access_token": "...", "refresh_token": "...", "token_type": "bearer", "expires_in": 900}} when sign-in is complete.
• {"mfa_required": true, "mfa_token": "..."} when the account uses MFA. Send the mfa_token and the 6-digit code to POST /api/auth/mfa/verify within 5 minutes to get the tokens.

Send the access token in the Authorization header:

Authorization: Bearer <access_token>

Access tokens last ACCESS_TOKEN_MINUTES (15 by default). Get a new one with POST /api/auth/refresh, passing {"refresh_token": "..."}. Browsers use the onx_refresh httpOnly cookie instead. Sessions last REFRESH_TOKEN_DAYS (7 by default).

#API keys (for scripts and CI)

Create a key under Settings → Password, MFA & SSO → API keys, or with POST /api/auth/api-keys (name, expires_in_days from 1 to 365, default 90). You get an access key (onx_ak_...) and a secret key (onx_sk_...). The secret is shown once and stored only as a hash.

Send both in one header, joined by a dot:

X-API-Key: <access_key>.<secret_key>

An API key acts as the user who created it, with that user's permissions. Revoke it with DELETE /api/auth/api-keys/{key_id}. You can also trade a key for a normal session with POST /api/auth/login/api-key.

#Choosing a project

Most data belongs to a project. Each request works in one project:

• the X-Project-Id header, or
• the project query parameter, or
• your default project when neither is set.

GET /api/auth/me lists the projects you can use. If you belong to no project, project endpoints return 403 with the code no_project.

#Permissions

Each endpoint checks a module and a level (read, modify or full), for example cloud: full to approve an infrastructure deployment. When your role is not enough, the API returns 403 with a message naming the access you need. See Access control.

#Errors

Every error has the same JSON shape:

{"error": {"code": "not_found", "message": "Integration not found"}}

Validation errors add the fields that failed:

{
  "error": {
    "code": "validation_error",
    "message": "Some fields are invalid",
    "details": {"fields": [{"field": "name", "message": "Field required"}]}
  }
}

#Pagination

Large lists return a page object:

{"items": [], "total": 0, "page": 1, "page_size": 25}

Use the page (from 1) and page_size query parameters. The maximum page_size is 200 (100 for a job's runs). These endpoints are paged:

• GET /api/users
• GET /api/builds
• GET /api/audit-logs
• GET /api/ci/jobs/{job_id}/runs
• GET /api/cloud/resources (also returns facets)
• GET /api/notifications/deliveries

Other lists return a plain JSON array.

#Examples

List the latest failed builds in a project with an API key:

curl -s "https://opsnexus.example.com/api/builds?status=failed&page_size=10" \
  -H "X-API-Key: $ONX_ACCESS_KEY.$ONX_SECRET_KEY" \
  -H "X-Project-Id: $ONX_PROJECT_ID"

Start a run of an OpsNexus pipeline on a branch, with parameters:

curl -s -X POST "https://opsnexus.example.com/api/ci/jobs/$JOB_ID/build" \
  -H "X-API-Key: $ONX_ACCESS_KEY.$ONX_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"branch": "main", "params": {"ENV": "staging"}}'

Download the audit log as CSV for the last week:

curl -s "https://opsnexus.example.com/api/audit-logs/export.csv?since=2026-11-01T00:00:00Z" \
  -H "Authorization: Bearer $ONX_TOKEN" -o audit-logs.csv

#Endpoints

Paths below are relative to the host. Methods follow REST conventions: GET reads, POST creates or runs an action, PUT replaces, PATCH changes some fields, DELETE removes.

#Authentication and sessions

#Profile

#Access control

#Projects

#Organization and settings

#Integrations (external CI/CD tools)

#Pipelines and builds (all tools)

#OpsNexus pipelines

The runner endpoints are called by build agents with their agent ID and secret, not by users:

#Pipeline plugins

#Build agents

#Secrets and variables

#Cloud accounts, resources and cost

#Infra designer

Called by the deployment pipeline with a one-time run token, not by users:

#Kubernetes

#Servers, SSH and Remote Desktop

#Monitoring, alerts and notifications

#Domains, SEO and traffic

#Artifacts, registries, marketplace and security

#Dashboards and reports

#Backup, VS Code and system

#Related

• Access control explains modules and permission levels.
• Audit logs covers what the API records.
• Environment variables lists ACCESS_TOKEN_MINUTES, REFRESH_TOKEN_DAYS and the other settings mentioned here.