Skip to main content

Documentation index for AI agents: llms.txt. Every page here is also served as markdown: add .md to its address, or request it with Accept: text/markdown.

Authentication

Endpoints accept either of two credentials unless an operation says otherwise.

1. Session cookie (web clients)

Call POST /api/auth/login with email and password to get a session cookie. The cookie is sent automatically with later requests. Session writes are CSRF protected (send X-CSRF-Token on POST, PUT, PATCH and DELETE).

2. API key (agents, integrations, scripts)

Owners and admins create keys in Organization settings > Developer. A key is vs_ followed by 64 hexadecimal characters and is shown once. Send it as any of:

  • Authorization: Bearer vs_... header (recommended)
  • X-API-Key: vs_... header
  • ?api_key=vs_... query parameter

API access comes with every paid plan (Solo, Starter, Business, Agency and custom Enterprise plans). On a plan without it (Free) every key request returns 403 with code API_ACCESS_NOT_IN_PLAN.

Scopes have the form {resource}:{read|write}:

  • GET requests need {resource}:read. POST, PUT, PATCH and DELETE need {resource}:write. In the dashboard, choosing write also grants read.
  • {resource}:* grants read and write on one resource. * grants every resource.
  • A missing scope returns 403 with code SCOPE_DENIED and names the scope the request needs.
  • Platform admin endpoints under /api/admin/* are blocked for API keys whatever the scope.
  • CSRF checks are skipped for API key requests.
  • The role of the member who created the key applies, so a key made by a viewer cannot write.

Resources and the paths they cover:

  • monitors: /api/monitors/*, /api/monitoring/*, /api/metrics/*, /api/dependencies/*, /api/reports/*, /api/dns/*
  • incidents: /api/incidents/*
  • servers: /api/servers/*
  • status-pages: /api/status-pages/*
  • alerts: /api/alerts/*, /api/alert-rules/*, /api/alert-groups/*
  • channels: /api/notification-channels/*, /api/notifications/*
  • maintenance: /api/maintenance/*
  • organization: /api/organization/*, /api/settings/*, /api/plan, /api/integrations/*
  • user: /api/user/*, /api/profile/*, /api/onboarding/*

Other paths, for example /api/overview, /api/workspace/*, /api/insights/*, /api/analytics/* and /api/billing/*, resolve to the general resource and need a key with the * scope. The dashboard does not create * keys.

Session-only endpoints (cookie required)

These endpoints stay session-only by design. An API key on them returns 403 with code SESSION_REQUIRED (or 401 where no session exists):

  • /api/auth/* (login, logout, refresh, 2FA, password reset, OAuth)
  • /api/billing/checkout, /api/billing/change-plan, /api/billing/portal (billing changes)
  • DELETE /api/organization, member and invitation management under /api/organization/members and /api/organization/invitations, POST/PUT/DELETE /api/organization/smtp, POST /api/organization/leave, and POST/PATCH/DELETE /api/api-keys (account and access management)
  • /api/integrations/slack/auth (OAuth start)
  • /api/organization/invitations/accept (email link flow)
  • /api/user/delete-account
  • /api/user/organizations/switch (changes the session cookie)
  • /api/chat/*, /api/ai/*, /api/incidents/{id}/summarize, /api/alert-groups/{id}/summarize, /api/reports/digest, POST /api/monitors/{id}/anomalies, POST /api/monitors/{id}/report (AI and reporting features)

From the Visual Sentinel OpenAPI 3.1 specification at https://docs.visualsentinel.com/openapi.json. Endpoint details are in the API reference.