API Overview

🔧 API Reference 8 min read Updated June 2026

The Gridlock REST API gives you programmatic access to every capability available through the dashboard — running AI agents, querying threat data, managing accounts, pulling compliance reports, and more. Whether you're building integrations, automating MSP workflows, or embedding Gridlock data into your own tooling, the API is your entry point.

This reference covers the foundational concepts that apply across every endpoint: the base URL, how authentication works, request and response conventions, rate limits, and error handling. Read this first before diving into specific endpoint documentation.

Base URL

All API requests are made over HTTPS to the following base URL. HTTP requests are automatically redirected to HTTPS and all non-HTTPS traffic is rejected at the edge.

https://lockthegrid.com/api

Example: to fetch the currently authenticated user's profile, you would request:

GET https://lockthegrid.com/api/user/profile

Authentication Methods

The Gridlock API supports two authentication methods depending on your use case. Both are passed via the standard HTTP Authorization header.

Method	Header Value	Best For	Expiry
JWT Bearer Token	Bearer <token>	Web app sessions, dashboard interactions	7 days
API Key	Bearer gl_live_<key>	Server-to-server, scripts, integrations	Configurable or never

See the Authentication guide for full details on obtaining tokens, generating API keys, scopes, rotation, and security best practices.

Request Format

All requests that include a body (POST, PUT, PATCH) must send JSON and set the appropriate content type header. GET and DELETE requests do not include a body.

Content-Type: application/json

A typical POST request looks like:

POST https://lockthegrid.com/api/agents/run
Authorization: Bearer gl_live_abc123xyz
Content-Type: application/json

{
  "agent": "threat-researcher",
  "target": "acmecorp.com",
  "options": {
    "include_cve": true,
    "mitre_mapping": true
  }
}

Response Format

Every response from the Gridlock API is JSON. Successful responses always include a top-level success: true field alongside the relevant data payload. Error responses use success: false and include an error message string.

Success Response

{
  "success": true,
  "data": {
    "agent_run_id": "run_9f3a1b2c",
    "agent": "threat-researcher",
    "status": "queued",
    "estimated_completion_seconds": 45
  }
}

Error Response

{
  "error": "Invalid agent name. Must be one of: msp-hunter, threat-researcher, tech-support, compliance, account-manager, onboarding"
}

Error messages are human-readable and safe to surface in developer tooling. They never include stack traces, internal service names, or database details.

HTTP Status Codes

The API uses standard HTTP status codes to indicate the result of every request. Your client should handle all of the following.

Code	Name	Meaning
200	OK	Request succeeded. Response body contains the requested data.
201	Created	Resource was created successfully. Used for POST requests that create new entities.
400	Bad Request	The request was malformed, missing required fields, or contained invalid values. Check the error field for specifics.
401	Unauthorized	No valid credentials were provided, or the token has expired. Re-authenticate and retry.
403	Forbidden	Valid credentials were provided, but they do not have permission to perform this action. Check your API key scopes.
404	Not Found	The requested resource does not exist. Double-check the path and any resource IDs in the URL.
429	Too Many Requests	Rate limit exceeded. See the Retry-After response header for how many seconds to wait before retrying.
500	Internal Server Error	An unexpected error occurred on the Gridlock side. These are automatically reported to our monitoring. If persistent, contact support.

Rate Limits

Rate limits are enforced per IP address and per API key. Limits vary by plan and endpoint category. When a limit is exceeded, the API returns 429 Too Many Requests and includes a Retry-After header indicating when you may retry.

Endpoint Category	Limit	Window	Notes
General API	100 requests	per minute, per IP	Applies to all authenticated requests
Auth endpoints (/api/auth/*)	10 requests	per minute, per IP	Stricter limit to prevent brute force
Agent execution	20 runs	per minute, per account	Applies across all agent types combined
Webhook delivery	N/A — inbound only	—	Gridlock does not rate limit webhook receipt

API Versioning

The Gridlock API is currently at version 1. There is no version prefix in the URL path — all requests to /api/* target v1 automatically. This design keeps integration code simple and avoids version drift in stored URLs or configuration.

When a breaking change requires a new version, Gridlock will:

• Announce the new version at least 60 days before it becomes available.
• Maintain both versions in parallel for a minimum of 6 months.
• Send email notice to all account owners with active API keys.
• Provide a migration guide documenting every breaking change with before/after examples.

Non-breaking additions — new optional fields in responses, new optional request parameters, new endpoints — are released without versioning and will not require any changes to existing integrations.

SDK & Library Availability

There is currently no official Gridlock SDK. All integrations use raw HTTP requests. The API is intentionally simple enough that a thin wrapper in any language takes under an hour to build.

Any HTTP client works. Examples in this documentation use curl for shell and the native fetch API for JavaScript. The patterns shown apply directly to libraries like axios, Python's requests, Go's net/http, or any other HTTP client you prefer.

Getting Your API Key

API keys are generated in the Gridlock dashboard. Each key can be scoped to specific permissions and given an optional expiry date.

1. Log in to lockthegrid.com/dashboard.
2. Navigate to Settings → API Keys in the left sidebar.
3. Click Generate New Key.
4. Give the key a descriptive name (e.g., "GitHub Actions Integration", "Zapier Webhook").
5. Select the permission scopes required (read, write, admin — choose the minimum necessary).
6. Set an optional expiry date. For production integrations, we recommend 90-day rolling keys.
7. Click Create Key. Copy the key immediately — it is shown only once.

Quick Start Example

Here is a minimal example showing a complete authenticated API request. This call fetches the current account's threat summary using a curl command.

curl -s \
  -H "Authorization: Bearer gl_live_your_key_here" \
  -H "Content-Type: application/json" \
  https://lockthegrid.com/api/threats/summary

And the same request in JavaScript using the native fetch API:

const response = await fetch('https://lockthegrid.com/api/threats/summary', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer gl_live_your_key_here',
    'Content-Type': 'application/json'
  }
});

if (!response.ok) {
  const err = await response.json();
  throw new Error(err.error);
}

const data = await response.json();
console.log(data);

Related Pages