API v2.0

Cyberhaven API v2.0 is the modern OpenAPI implementation for platform configuration and data querying. Use these endpoints to integrate with SIEMs, SOAR, ticketing, and asset management tools.

Base URL

https://<tenant-name>.cyberhaven.io/v2/

Request Methods

The API supports multiple request methods for different use cases:

Method	Use Case	Description
GET	Simple queries	Basic requests with few parameters via query string
POST	Complex queries	Recommended for requests with filtering, pagination, or large parameter sets
PATCH	Updates	Partial updates to existing resources
DELETE	Removal	Remove resources from management

Request Method Examples

GET with Query Parameters

GET /v2/event-details?ids=event1,event2&include_content=true

GET with Path Parameters

GET /v2/installer/windows/latest

POST with Request Body (Recommended)

POST /v2/incidents/list
{
  "filter": {
    "policy_severities": ["high", "critical"]
  },
  "page_request": {
    "size": 50
  }
}

Data Types

Primitive Types

Type	Description	Example
string	Text value	"example-value"
integer	Whole number	42
boolean	True/false value	true
number	Decimal number	3.14

Complex Types

Type	Description	Example
array[string]	List of text values	["item1", "item2", "item3"]
array[object]	List of objects	[{"id": "1"}, {"id": "2"}]
object	Structured data	{"field": "value", "count": 10}

Time Formats

Format	Description	Example
ISO 8601	Standard timestamp format	"2024-01-15T10:30:00Z"
Duration	Time duration	"30s", "5m", "1h"

Response Headers

Standard response headers included with API responses:

Header	Description	Example
Content-Type	Response format	application/json
Content-Length	Response size in bytes	1024
X-RateLimit-Remaining	Requests remaining in current window	45
X-RateLimit-Reset	Time when rate limit resets	1642248600

Binary Response Headers

For file downloads (e.g., installers):

Header	Description	Example
Content-Type	Binary content type	application/octet-stream
Content-Disposition	Download filename	attachment; filename="installer.msi"
X-Installer-Version	Software version	24.03.90.366

Response Objects

Standard Response Structure

Field	Type	Description
type	string	Resource type identifier
size	integer	Number of items returned
resources	array	Array of resource objects
errors	array[Error]	Any errors encountered

Error Object Structure

Field	Type	Description
code	string	Error code identifier
message	string	Human-readable error description
details	object	Additional error context

Example Response

{
  "type": "events",
  "size": 2,
  "resources": [
    {
      "id": "event-123",
      "timestamp": "2024-01-15T10:30:00Z"
    }
  ],
  "errors": []
}

Pagination Controls

Page Request Object

Field	Type	Required	Description
size	integer	No	Number of results per page (max 1000, default 50)
id	string	No	Page token for next page (from previous response)
sort_by	string	No	Sort field and direction

Page Response Object

Field	Type	Description
next_id	string	Token for retrieving next page
total	integer	Total number of matched resources

Sort Options

Format	Description	Example
field asc	Ascending order	"hostname asc"
field desc	Descending order	"timestamp desc"

Pagination Example

{
  "page_request": {
    "size": 100,
    "sort_by": "timestamp desc"
  }
}

Status Codes

Success Codes

Code	Status	Description
200	OK	Request successful
201	Created	Resource created successfully
204	No Content	Request successful, no response body

Client Error Codes

Code	Status	Description
400	Bad Request	Invalid request parameters or format
401	Unauthorized	Invalid or expired access token
403	Forbidden	Insufficient permissions for operation
404	Not Found	Requested resource not found
409	Conflict	Resource conflict (e.g., duplicate name)
429	Too Many Requests	Rate limit exceeded

Server Error Codes

Code	Status	Description
500	Internal Server Error	Platform issue, contact support
502	Bad Gateway	Temporary service unavailability
503	Service Unavailable	Planned maintenance or overload

Rate Limiting

Standard Limits

Limit Type	Value	Description
Requests per minute	60	Maximum requests per API key per minute
Concurrent requests	5	Maximum simultaneous requests per endpoint
Response on limit	429	HTTP status code when limits exceeded

Rate Limit Headers

Header	Description
X-RateLimit-Remaining	Requests remaining in current window
X-RateLimit-Reset	Unix timestamp when limit resets

Authentication

All API calls require Bearer token authentication:

Authorization: Bearer <access-token>

See Authentication Guide for token generation details.