API Reference

REST API Reference

Integrate CleanShift into your infrastructure with our JSON REST API. All endpoints require a JWT bearer token unless noted otherwise.

Authentication

Include your token in every request: Authorization: Bearer <YOUR_TOKEN>. Obtain a token via POST /auth/login. Tokens expire after 24 hours; use the refresh token to obtain a new one. API access is available on all plans.

Authentication

POST/auth/login

Authenticate with email + password. Returns a JWT access token and refresh token.

No auth

POST/auth/register

Create a new account. Returns user object and initial API key.

No auth

Servers

Manage the servers (nodes) registered to your account. Each server runs the CleanShift agent.

GET/servers

List all registered servers with status, last check-in time, and site count.

POST/servers/register

Scans

Trigger on-demand scans and retrieve results. Scans include file, database, and vulnerability checks.

POST/scans/trigger

Queue a new scan on a server or specific site. Accepts scan_mode (quick | full | deep).

GET/scans/{id}

Retrieve scan results by ID including threat counts, timestamps, and finding details.

Threats

View, manage, and remediate detected threats across your fleet.

GET/threats

List all detected threats with filtering by severity, status, server, and site.

PATCH/threats/{id}

Update a threat's status (acknowledge, false-positive, resolved). Supports bulk operations.

POST/threats/{id}/remediate

Trigger auto-remediation for a specific threat using the appropriate CVE playbook.

Agent

Endpoints used by the on-server agent for heartbeat check-ins and real-time communication.

POST/agent/checkin

Periodic heartbeat from the agent. Reports server health, site inventory, and pending results.

WS/ws/agent

WebSocket connection for real-time bidirectional communication — push scan commands, stream results.

Example Request

trigger a scan

$ curl -X POST https://api.cleanshift.osg.co.in/scans/trigger \

-H "Authorization: Bearer $CS_TOKEN" \

-H "Content-Type: application/json" \

-d '{"server_id": "srv_abc123", "scan_mode": "deep"}'

# Response

{"scan_id": "scn_x7k9m2", "status": "queued", "estimated_duration": "45s"}

Detail	Value
Base URL	https://api.cleanshift.osg.co.in
Rate Limit	100 requests / minute per token
Response Format	JSON (application/json)
WebSocket Protocol	wss:// with JWT query param
Token Expiry	24 hours (refresh tokens: 30 days)
API Versioning	URL path — currently /v1 (implied)

Ready to integrate?

Get API Key