API Reference

Build on the ImaraForge platform with our RESTful API. Authenticate with Bearer tokens, manage devices, run scans, and automate your security workflows.

Authentication

All API requests require a Bearer token. Obtain one via the login endpoint or use an API key for service-to-service calls.

# Authenticate and get a Bearer token curl -X POST https://api.imaraforge.com/api/auth/login \ -H "Content-Type: application/json" \ -d '{"email": "[email protected]", "password": "••••••••"}' # Use the token in subsequent requests curl https://api.imaraforge.com/api/devices \ -H "Authorization: Bearer <your-token>"

Core Endpoints

Devices

Register, list, and manage endpoint devices across your organization.

  • GET/api/devices
  • POST/api/devices/enroll
  • GET/api/devices/{id}
  • PUT/api/devices/{id}

Vulnerabilities

Scan results, vulnerability details, and remediation tracking.

  • GET/api/vulnerabilities
  • GET/api/vulnerabilities/{id}
  • POST/api/scans/trigger

Patches

Patch inventory, deployment scheduling, and compliance reporting.

  • GET/api/patches
  • POST/api/patches/deploy
  • GET/api/patches/compliance

Compliance

Compliance status, audit reports, and regulatory framework mappings.

  • GET/api/compliance/status
  • GET/api/compliance/report

Webhooks

Subscribe to real-time events for security alerts, scan completions, and compliance changes.

  • GET/api/webhooks
  • POST/api/webhooks
  • DEL/api/webhooks/{id}

Analytics

Dashboard metrics, trend data, and executive reporting endpoints.

  • GET/api/admin/analytics
  • GET/api/dashboard/metrics

Rate Limiting

API requests are rate-limited to ensure fair usage and platform stability.

# Rate limit headers are included in every response X-RateLimit-Limit: 200 X-RateLimit-Remaining: 187 X-RateLimit-Reset: 1709942400 # When rate limited, you'll receive a 429 response HTTP/1.1 429 Too Many Requests {"error": "Too many requests", "retry_after": 60}

Webhook Events & Payloads

Configure webhooks at Settings → Integrations → Webhooks. All payloads include an X-ImaraForge-Signature HMAC header for verification.

# Event: scan.completed { "event": "scan.completed", "timestamp": "2026-04-08T14:30:00Z", "data": { "device_id": "dev_abc123", "device_name": "ENG-LAPTOP-042", "scan_id": "scn_xyz789", "vulnerabilities_found": 12, "critical": 2, "high": 4, "medium": 6, "duration_seconds": 145 } }
# Event: alert.created { "event": "alert.created", "timestamp": "2026-04-08T14:32:00Z", "data": { "alert_id": "alt_def456", "severity": "critical", "title": "CVE-2026-1234 detected on 3 devices", "affected_devices": ["dev_abc123", "dev_ghi789", "dev_jkl012"], "cve_id": "CVE-2026-1234", "cvss_score": 9.8 } }
# Event: device.enrolled { "event": "device.enrolled", "timestamp": "2026-04-08T10:15:00Z", "data": { "device_id": "dev_new001", "device_name": "SALES-PC-007", "os": "Windows 11 Pro 23H2", "agent_version": "1.2.0", "enrollment_key": "enr_abc***" } }
# Event: compliance.changed { "event": "compliance.changed", "timestamp": "2026-04-08T16:00:00Z", "data": { "framework": "CIS", "previous_score": 87, "current_score": 72, "direction": "decreased", "threshold_breach": true, "failing_controls": ["5.1.2", "6.2.1", "7.1.4"] } }

Additional events: device.offline, patch.deployed, patch.failed, user.invited

Error Codes

Standard HTTP error codes with ImaraForge-specific error bodies.

Code Status Description Resolution
400Bad RequestMissing or invalid request parameters.Check request body, query params, and content type.
401UnauthorizedMissing, invalid, or expired authentication token.Re-authenticate or generate a new API key.
403ForbiddenAuthenticated but insufficient permissions or tier.Verify user role and subscription tier.
404Not FoundRequested resource does not exist.Verify the resource ID and endpoint path.
409ConflictResource already exists (e.g., duplicate enrollment).Check for existing resource before creating.
422UnprocessableRequest is well-formed but semantically invalid.Review the error details in the response body.
429Too Many RequestsRate limit exceeded for your tier.Back off using Retry-After header value.
500Internal ErrorServer-side failure. Includes a request ID for support.Retry after 30s. If persistent, contact support with the request ID.
# Error response body format { "error": "validation_error", "message": "Field 'device_name' is required", "request_id": "req_abc123def456", "details": [ {"field": "device_name", "issue": "required"} ] }

Response Examples

Standard response shapes for common API endpoints.

# GET /api/devices — List devices { "data": [ { "id": "dev_abc123", "name": "ENG-LAPTOP-042", "os": "Windows 11 Pro 23H2", "agent_version": "1.2.0", "status": "online", "health_score": 87, "last_scan": "2026-04-08T14:30:00Z", "group": "Engineering" } ], "pagination": { "page": 1, "per_page": 25, "total": 42, "total_pages": 2 } }
# GET /api/vulnerabilities/{id} — Vulnerability detail { "id": "vuln_xyz789", "cve_id": "CVE-2026-1234", "title": "Remote Code Execution in OpenSSL 3.x", "severity": "critical", "cvss_score": 9.8, "affected_devices": 3, "status": "open", "discovered_at": "2026-04-07T09:15:00Z", "remediation": "Update OpenSSL to 3.1.5 or later", "patch_available": true }

SDKs & Libraries

Official client libraries for seamless integration with your workflow.

Python SDK

Full-featured Python client for automation, scripting, and CI/CD integration.

pip install imaraforge from imaraforge import Client client = Client(api_key="your-key") devices = client.devices.list() for d in devices: print(d.name, d.health_score)

Node.js SDK

TypeScript-ready client for Node.js backend integrations and serverless functions.

npm install @imaraforge/sdk import { ImaraForge } from '@imaraforge/sdk'; const client = new ImaraForge({ apiKey: 'your-key' }); const alerts = await client.alerts.list({ severity: 'critical' });