REST API Reference

Automate compliance reporting, trigger scans, and pull findings into your SIEM or CI pipeline.

Base URL: https://corvus-security.net

Authentication

All requests must include an API token in the Authorization header.

Request header

Authorization: Bearer csk_your_token_here

How to get an API token

  1. Open the dashboard at app.corvus-security.net
  2. Go to Settings → Security
  3. Scroll to API Tokens and click New token
  4. Copy the token immediately — it is only shown once

Tokens start with csk_ and are stored as SHA-256 hashes — never in plain text.

Example — curl

curl -s \
  -H "Authorization: Bearer csk_your_token_here" \
  "https://corvus-security.net/api/v1/tenants/{tenant_id}/agents"

Tenant ID

Every API endpoint is scoped to a tenant. Your tenant ID is a UUID shown in the dashboard URL and in the Settings → License tab.

https://app.corvus-security.net/  ← navigate here, see tenant ID in Settings → License

All endpoints below use {tenant_id} as a placeholder for your actual UUID.

Agents

GET /api/v1/tenants/{tenant_id}/agents

List all enrolled agents with their status, OS info, and latest scan scores.

Response 200

{
  "agents": [
    {
      "id": "agt_01j...",
      "hostname": "DESKTOP-ABC123",
      "os": "windows",
      "os_version": "Windows 11 Pro",
      "agent_version": "1.2.0",
      "status": "online",              // "online" | "offline"
      "last_seen_at": "2026-03-28T10:14:00Z",
      "last_scan_score": 78.4,
      "last_scan_at": "2026-03-28T09:00:00Z",
      "scan_count": 42,
      "available_packs": ["windows11-cis-l1", "windows10-cis-l1"],
      "created_at": "2026-01-15T08:00:00Z"
    }
  ]
}
GET /api/v1/tenants/{tenant_id}/agents/{agent_id}

Returns full detail for a single agent. Same schema as the list item above.

Jobs & Scans

A job is a unit of work sent to an agent. Currently supports scan (collect & evaluate) and remediate (apply fix & rescan) job types.

GET /api/v1/tenants/{tenant_id}/jobs

List all jobs for the tenant, newest first.

Response 200

{
  "jobs": [
    {
      "id": "job_01j...",
      "agent_id": "agt_01j...",
      "rule_pack_id": "windows11-cis-l1",
      "level": 1,
      "job_type": "scan",             // "scan" | "remediate"
      "status": "completed",          // "pending" | "running" | "completed" | "failed"
      "score": 78.4,
      "created_at": "2026-03-28T09:00:00Z",
      "started_at": "2026-03-28T09:00:05Z",
      "finished_at": "2026-03-28T09:00:23Z"
    }
  ]
}
POST /api/v1/tenants/{tenant_id}/jobs

Queue a new scan or remediation job for an agent.

Request body

{
  "agent_id":     "agt_01j...",  // required
  "rule_pack_id": "windows11-cis-l1",
  "level":        1,             // 1 or 2
  "job_type":     "scan",        // optional, default "scan"
  "rule_ids":     []             // optional: target specific rules
}

Response 201

{
  "id": "job_01j...",
  "status": "pending",
  "agent_id": "agt_01j...",
  "rule_pack_id": "windows11-cis-l1",
  "level": 1,
  "job_type": "scan",
  "created_at": "2026-03-28T10:00:00Z"
}

Example — trigger a full scan

curl -s -X POST \
  -H "Authorization: Bearer csk_your_token" \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"agt_01j...","rule_pack_id":"windows11-cis-l1","level":1}' \
  "https://corvus-security.net/api/v1/tenants/{tenant_id}/jobs"
GET /api/v1/tenants/{tenant_id}/jobs/{job_id}

Poll job status. When status === "completed", fetch findings separately.

Poll every 3–10 seconds. The agent typically completes a full scan in 10–30 seconds.

Findings

GET /api/v1/tenants/{tenant_id}/jobs/{job_id}/findings

Returns the full finding set for a completed job. Only available once status === "completed".

Response 200

{
  "findings": [
    {
      "rule_id":     "CIS-W11-L1-1.1.1",
      "title":       "Password history: 24 passwords remembered",
      "status":      "pass",           // "pass" | "fail" | "error" | "not_applicable"
      "level":       1,
      "category":    "Account Policies",
      "observed":    24,               // value found on the endpoint
      "expected":    24,               // required value per CIS
      "remediation": "Set via Group Policy: ...",
      "evidence":    "Registry: HKLM\\... = 24",
      "error":       null              // collection error string if applicable
    }
  ]
}

Reports

GET /api/v1/tenants/{tenant_id}/jobs/{job_id}/report

Download a formatted report for a completed job.

Query param Value Description
format json Full JSON report (all findings)
format csv CSV export (one row per finding)
format html Printable HTML report (self-contained)

Example — download CSV

curl -s \
  -H "Authorization: Bearer csk_your_token" \
  "https://corvus-security.net/api/v1/tenants/{tenant_id}/jobs/{job_id}/report?format=csv" \
  -o report.csv

Policies

Policies define which rule pack and CIS level to apply to an agent, optionally on a schedule.

GET /api/v1/tenants/{tenant_id}/policies List all policies
POST /api/v1/tenants/{tenant_id}/policies Create a policy
PUT /api/v1/tenants/{tenant_id}/policies/{policy_id} Update a policy
DELETE /api/v1/tenants/{tenant_id}/policies/{policy_id} Delete a policy

Policy object

{
  "id":           "pol_01j...",
  "name":         "Windows 11 Daily Scan",
  "description":  "Full CIS L1 scan every day at midnight",
  "rule_pack_id": "windows11-cis-l1",
  "level":        1,
  "categories":   [],            // empty = all categories
  "schedule":     "0 0 * * *",   // cron expression, or empty for manual
  "created_at":   "2026-01-15T08:00:00Z"
}

API Tokens

Manage API tokens programmatically. Tokens can also be managed via the dashboard (Settings → Security → API Tokens).

GET /api/v1/tenants/{tenant_id}/api-tokens List tokens (no raw values)
POST /api/v1/tenants/{tenant_id}/api-tokens Create a token — returns raw value once
DELETE /api/v1/tenants/{tenant_id}/api-tokens/{token_id} Revoke a token
The raw token value is returned only once at creation. Store it securely — it cannot be retrieved again.

License

GET /api/v1/tenants/{tenant_id}/license

Returns current plan, agent limit, and subscription status.

{
  "plan":                "standard",     // "starter" | "standard" | "professional" | "company"
  "max_agents":          15,
  "agent_count":         4,
  "subscription_status": "active",
  "current_period_end":  "2026-04-28T00:00:00Z"
}

Errors

All errors return JSON with an error field.

Status Meaning
200 / 201 Success
401 Missing or invalid API token
403 Token valid but insufficient permissions for this resource
404 Resource not found
422 Validation error — check the request body
429 Rate limit exceeded

Error response example

{ "error": "Unauthorized" }
← Agent Deployment Docs overview