Requests and responses

The Elastio API is a JSON-over-HTTPS REST API. This page describes the conventions most operations follow. The API is served by several backend services behind one gateway, so details vary between areas: when in doubt, the operation’s entry in the API reference is authoritative.

Requests

Base URL and paths

Send every request to your tenant, https://{tenant}.app.elastio.com, over HTTPS. Paths begin with the service prefix and a version, for example /gateway/api/v2/incidents or /rbac/api/v1/users. See Versioning.

Headers

Header	When to send it
`Authorization: Bearer <token>`	On every request. See Authentication.
`Content-Type: application/json`	On requests with a JSON body (most `POST`, `PUT` and `PATCH` operations).
`Accept: application/json`	Optional. Most responses are JSON.
`If-Match`	Optional on `PATCH /gateway/shared-services/v1/resilience-program/overrides/{override_id}`: send the `version` you read to make the write conditional.

Request bodies

Write operations take a JSON object. Field names are snake_case in most of the API, but some services use camelCase, so copy names from the schema in the reference rather than guessing. Two operations, POST and PATCH on /gateway/shared-services/v3/yara-rulesets, take multipart/form-data to upload rule files.

curl -X POST "https://acme.app.elastio.com/gateway/api/v2/incidents/7d2e9f40-1c3b-4a8e-b5d6-2f9a0c1e3b47/close" \
  -H "Authorization: Bearer $ELASTIO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "version": 3, "reason": "remediated", "comment": "Restored from the last clean recovery point." }'

import os, requests

BASE = "https://acme.app.elastio.com"
HEADERS = {"Authorization": f"Bearer {os.environ['ELASTIO_TOKEN']}"}

incident_id = "7d2e9f40-1c3b-4a8e-b5d6-2f9a0c1e3b47"
body = {"version": 3, "reason": "remediated", "comment": "Restored from the last clean recovery point."}
resp = requests.post(f"{BASE}/gateway/api/v2/incidents/{incident_id}/close", headers=HEADERS, json=body, timeout=30)
resp.raise_for_status()

$Base = "https://acme.app.elastio.com"
$Headers = @{ Authorization = "Bearer $env:ELASTIO_TOKEN" }
$IncidentId = "7d2e9f40-1c3b-4a8e-b5d6-2f9a0c1e3b47"
$Body = @{ version = 3; reason = "remediated"; comment = "Restored from the last clean recovery point." } | ConvertTo-Json

Invoke-RestMethod -Method Post -Uri "$Base/gateway/api/v2/incidents/$IncidentId/close" `
    -Headers $Headers -ContentType "application/json" -Body $Body

Version-checked writes

Some resources protect against lost updates with a version number. Incident actions (close, reopen, comment, assign) take the incident’s current version in the body; read the incident first, then send the version you saw. Resilience program overrides accept the same idea through the If-Match header, and a number of operations, for example POST /gateway/shared-services/v1/policies, document 412 Precondition Failed. If a version-checked write fails, re-read the resource and decide whether to retry.

Identifiers

Most resource IDs are UUIDs, such as asset_id, incident id, token id and policy id values: 0b6f3c1e-8a52-4c2e-9d1f-5e7a2b9c4d10.
Some resources are addressed by name in the path, for example PUT /gateway/shared-services/v1/policies/{name}.
Cloud identifiers keep their native form: AWS account IDs (123456789012), regions (us-east-1), AMI IDs (ami-…).
Some resources also have a human-readable handle alongside the UUID, such as the incident handle (INC-000001) or a cloud connector job ID (j-…). Use the UUID in API paths unless the operation says otherwise.

Treat all IDs as opaque strings. Don’t parse them or rely on their format.

Timestamps and dates

Timestamps are RFC 3339 strings, for example 2026-10-12T09:30:00Z, and are marked format: date-time in the spec. Send timestamps in the same format, such as expires_at when you issue a token.

A few filters take a plain date instead. GET /gateway/api/v1/jobs requires startDate and endDate as YYYY-MM-DD. Some operations take a rolling window, such as period=7d on alert activity. Check the parameter description.

Responses

Status codes

Successful requests return 200 OK, 201 Created (for example when you issue a token), 202 Accepted for work that continues in the background, or 204 No Content when there is no body (for example revoking tokens). Errors return 4xx or 5xx with a JSON body. See Errors.

Response bodies

Response shapes depend on the service:

Lists usually return an array of items plus paging information. GET /gateway/api/v2/assets returns data, total and pagination; GET /gateway/api/v2/incidents returns data and total; GET /gateway/integration/v2/alerts returns alerts and pagination. See Pagination.
Many /gateway/api/v1 operations wrap their result in an envelope with status, data, message and cache information (cached plus expires_in_ms or expiresInMs). For example, GET /gateway/api/v1/search/assets returns the assets under data.assets.
A few operations return binary content: the compliance reports under /gateway/api/v1/reports/compliance/…, EQL report PDFs and POST /gateway/shared-services/v1/documents/pdf return application/pdf.

Fields that have no value may be null or omitted. Write your code to handle both, and to ignore fields it doesn’t know.

Filtering

List operations take filters as query parameters. The common patterns:

Comma-separated lists. Most multi-value filters take a single parameter with comma-separated values. For example, on GET /gateway/api/v2/incidents:

severity=critical,high (values critical, high, medium, low, info)
finding_status=open,acknowledged (values open, acknowledged, suppressed, resolved)
type=threat,violation (values threat, violation, data_classification)

and on GET /gateway/api/v2/assets: platform=aws,azure, health=infected,at_risk, threat_kind=ransomware,malware, scan_coverage=not_covered, policy_id=<uuid>,<uuid>.

Single-value enums. Some filters take one value, such as status on incidents (open, closed or all, default open).

Structured filters. A few filters take JSON. tags on GET /gateway/api/v2/assets is a JSON array of tag filters, such as [{"key":"Environment","value":"prod"}]. URL-encode it.

Discover valid values. Several areas publish an endpoint that returns the filter values that make sense for your tenant, for example:

GET

/gateway/api/v2/assets/filtersGet contextual filter options for v2 assets

Try it

GET

/gateway/api/v2/incidents/filtersGet contextual filter options for incidents

Try it

GET

/gateway/api/v1/search/assets/filtersGet filter options for assets search

Try it

Parameter names are not uniform across services: you will see both snake_case (start_date, asset_id) and camelCase (startDate, assetIds). Some operations accept both spellings of a parameter as aliases, which the reference notes.

Search

Many list operations take a free-text search parameter. What it matches is documented per operation:

GET /gateway/api/v2/assets: asset name or UUID.
GET /gateway/api/v2/incidents: a substring of the handle, finding key, asset name or ID, title and method.
GET /gateway/api/v1/search/assets: asset name, region and subscription. It also takes alt_search, a comma-separated list of specific asset names.

curl -G "https://acme.app.elastio.com/gateway/api/v2/incidents" \
  -H "Authorization: Bearer $ELASTIO_TOKEN" \
  --data-urlencode "search=web-prod" \
  --data-urlencode "severity=critical,high" \
  --data-urlencode "sort_by=OPENED_AT_DESC"

params = {"search": "web-prod", "severity": "critical,high", "sort_by": "OPENED_AT_DESC"}
resp = requests.get(f"{BASE}/gateway/api/v2/incidents", headers=HEADERS, params=params, timeout=30)
resp.raise_for_status()

Invoke-RestMethod -Uri "$Base/gateway/api/v2/incidents?search=web-prod&severity=critical,high&sort_by=OPENED_AT_DESC" -Headers $Headers

Sorting

Sorting is controlled with sort_by, which takes FIELD_ASC or FIELD_DESC values:

GET /gateway/api/v2/incidents: one of SEVERITY_ASC, SEVERITY_DESC, OPENED_AT_ASC, OPENED_AT_DESC, HANDLE_ASC, HANDLE_DESC, ASSET_NAME_ASC, ASSET_NAME_DESC, ASSIGNEE_ASC, ASSIGNEE_DESC.
GET /gateway/api/v2/assets: a single field, such as ASSET_NAME_ASC or LAST_CLEAN_BACKUP_DESC. The default is health, descending.
GET /gateway/api/v1/search/assets: a comma-separated list of fields, such as HEALTH_DESC,REGION_ASC.

A few older operations use a sorting parameter instead, in the form detected_at:asc. Check the operation in the reference for the values it accepts.