API Endpoints

🔧 API Reference 10 min read Updated June 2026

All API endpoints are served from https://lockthegrid.com/api. Authenticated endpoints require a valid JWT bearer token in the Authorization header, obtained from POST /api/auth/login. All request bodies use application/json and all responses return JSON.

Authentication

Auth endpoints handle registration, login, session management, and password lifecycle. Most auth endpoints are public (no token required). The /me and /change-password endpoints require an active session.

Method	Path	Auth	Description	Key Parameters
POST	/api/auth/register	Public	Create a new user account. Returns a JWT token and triggers email verification.	email, password, name
POST	/api/auth/login	Public	Authenticate with email and password. Returns a signed JWT token.	email, password
POST	/api/auth/logout	Required	Invalidate the current session token on the server.	None (token from header)
POST	/api/auth/refresh	Required	Exchange a valid (non-expired) token for a fresh token with a new expiry window.	None (token from header)
GET	/api/auth/me	Required	Return the authenticated user's profile, organization membership, and role.	None
POST	/api/auth/change-password	Required	Update the user's password. Invalidates all existing sessions on success.	current_password, new_password
POST	/api/auth/reset-request	Public	Send a password reset email to the specified address if an account exists.	email
POST	/api/auth/reset-confirm	Public	Complete a password reset using the token from the reset email.	token, new_password

Dashboard

Dashboard endpoints power the main overview page, security score gauge, and threat timeline. All dashboard endpoints require authentication. Data is scoped to the authenticated user's organization.

Method	Path	Auth	Description	Key Parameters
GET	/api/dashboard/overview	Required	Aggregated overview: security score, event counts, agent status, recent alerts.	None
GET	/api/dashboard/security-score	Required	Current composite security score (0–100) with sub-scores by category.	None
GET	/api/dashboard/stats	Required	Numeric stats panel: threats blocked today, open alerts, compliance gaps, agents active.	None
GET	/api/dashboard/events	Required	Paginated list of recent security events for the events feed widget.	limit, offset, severity
GET	/api/dashboard/risk-timeline	Required	Time-series data for the risk score chart — one data point per day for the last 30 days.	days (default: 30)
GET	/api/dashboard/daily-summary	Required	Natural language summary of the day's threat activity, generated by the AI layer.	None
GET	/api/dashboard/network-health	Required	DNS query stats, blocked tracker counts, and active protection indicators.	None
GET	/api/dashboard/health	Public	Service health check endpoint for uptime monitoring. Returns {"status":"ok"}.	None

Agents

Agent endpoints expose Gridlock's six AI agents. Use GET /api/agents to list all agents and their current status, then POST /api/agents/:id/execute to run an agent with optional parameters. Executions are asynchronous — poll the execution record for status and results.

Method	Path	Auth	Description	Key Parameters
GET	/api/agents	Required	List all six agents with their name, description, status, last execution time, and plan tier.	None
POST	/api/agents/:id/execute	Required	Trigger an agent execution. Returns an execution ID immediately; results are available asynchronously. :id is the agent slug (e.g. msp-hunter).	prompt, agent-specific params (e.g. vertical, region)
GET	/api/agents/:id/executions	Required	List past executions for the given agent. Each record includes status, duration, and output summary.	limit, offset

Compliance

Compliance endpoints drive the framework progress dashboards (SOC 2, HIPAA, NIST, CIS Controls) and the automated remediation engine. Audit reports are generated asynchronously and can be downloaded once complete.

Method	Path	Auth	Description	Key Parameters
GET	/api/compliance	Required	Overview of all enabled compliance frameworks: name, completion percentage, open gaps, last audit date.	None
POST	/api/compliance/audit	Required	Trigger a full compliance audit for one or all frameworks. Returns a report ID; poll for completion.	framework (optional: soc2, hipaa, nist, cis)
GET	/api/compliance/templates	Required	List available policy templates (acceptable use, incident response, data classification, etc.) with download links.	None
POST	/api/compliance/remediate	Required	Trigger automated remediation for a specific compliance gap item identified in a prior audit. Returns remediation steps and execution status.	gap_id, auto_apply (boolean)

Events & Alerts

Security events are the raw signal feed — every detected threat, blocked connection, DNS anomaly, or policy violation is recorded as an event. Alerts are higher-priority distillations of events that require human review.

Method	Path	Auth	Description	Key Parameters
GET	/api/events	Required	Paginated list of all security events. Supports filtering by severity, type, and date range. Sortable by timestamp or severity.	severity, type, from, to, limit, offset
GET	/api/alerts	Required	Paginated list of active and resolved alerts. Each alert includes severity, category, affected asset, and recommended action.	status (open | resolved), severity, limit

Tickets

The ticket system powers AI-assisted support. End users and MSP technicians can submit tickets via the dashboard or the API. Tickets are triaged automatically by the Tech Support agent and escalated to a human queue when confidence is low.

Method	Path	Auth	Description	Key Parameters
POST	/api/tickets/submit	Required	Submit a new support ticket. The Tech Support agent automatically analyzes the ticket and generates an initial resolution suggestion within seconds.	subject, description, priority (low | medium | high)
GET	/api/tickets	Required	List all tickets for the organization, with status, assignee, and AI triage result. Admins see all tickets; members see only their own.	status, limit, offset
GET	/api/tickets/:id	Required	Full ticket detail: description, AI resolution steps, conversation thread, status history, and escalation log.	None

CVE Watchlist

The CVE Watchlist lets you pin specific CVEs for continuous monitoring. When new intelligence arrives for a watched CVE — updated CVSS score, new exploit code, affected vendor patch — the Threat Researcher agent fires a notification automatically.

Method	Path	Auth	Description	Key Parameters
GET	/api/cve-watchlist	Required	List all CVEs currently on the watchlist, with CVSS score, vendor, patch status, and last intelligence update timestamp.	None
POST	/api/cve-watchlist	Required	Add a CVE to the watchlist by ID. The Threat Researcher agent immediately runs an enrichment pass to populate MITRE ATT&CK mapping and affected assets.	cve_id (e.g. CVE-2024-12345)
DELETE	/api/cve-watchlist/:id	Required	Remove a CVE from the watchlist. Stops all monitoring and notifications for this CVE.	None (:id is the watchlist entry ID)

Outreach & Leads

Outreach endpoints expose the MSP Hunter lead pipeline. Leads are created by the MSP Hunter agent and can be read and status-updated via API — useful for syncing with external CRMs or building custom pipeline tooling.

Method	Path	Auth	Description	Key Parameters
GET	/api/outreach/leads	Required	List all MSP Hunter leads with score, contact data, pipeline status, and intelligence summary. Supports filtering by status and minimum score.	status, min_score, vertical, limit, offset
PATCH	/api/outreach/leads/:id/status	Required	Update a lead's pipeline status. Valid statuses: new, contacted, responded, qualified, won, lost. Status changes are logged in the lead's audit trail.	status, note (optional)

Error Codes

All errors return a JSON body with a error string and an optional code machine-readable identifier. HTTP status codes follow REST conventions.

HTTP Status	Code	Meaning
400	validation_error	Request body is missing required fields or fails validation. The response includes a fields array naming each invalid field.
401	unauthorized	No token provided, token is expired, or token is invalid.
403	plan_upgrade_required	The endpoint requires a higher plan tier than the account currently holds.
404	not_found	The requested resource does not exist or belongs to a different organization.
429	rate_limited	Too many requests. The Retry-After header contains the number of seconds to wait before retrying.
500	internal_error	Unexpected server error. The error is logged to Sentry automatically. Do not expose stack traces to end users.

Related