Quickstart

This quickstart takes you from nothing to a working script in a few minutes. You will issue a personal access token, check that you can reach your tenant, list your assets, follow a page of results, and list open incidents.

You need:

• An Elastio tenant, and the subdomain you use to sign in (for example acme in https://acme.app.elastio.com).
• A tenant admin account, or a tenant admin who can issue a token for you.
• curl, Python 3 with requests, or PowerShell 7.

1. Get a personal access token.

   Tenant admins issue tokens in the Elastio console. Give the token a descriptive name, grant it read access to the scope categories you need (for this quickstart, inventory and security), and copy the token value. It is shown only once.

   If you already have a token with admin rights, you can issue new ones through the API with POST /gateway/shared-services/v1/personal-access-tokens. See Issue a token with the API.

2. Store the token and tenant in your environment.

   Keep the token out of your source code. The examples on this site read it from ELASTIO_TOKEN.

   cURL

   export ELASTIO_TENANT="acme"
   export ELASTIO_TOKEN="<paste your token>"

   Python

   export ELASTIO_TENANT="acme"
   export ELASTIO_TOKEN="<paste your token>"
   pip install requests

   PowerShell

   $env:ELASTIO_TENANT = "acme"
   $env:ELASTIO_TOKEN = "<paste your token>"

3. Check that you can reach the API.

   GET

   /gateway/api/v1/health_checkCheck API health status

   Try it →
   cURL

   curl "https://$ELASTIO_TENANT.app.elastio.com/gateway/api/v1/health_check" \
     -H "Authorization: Bearer $ELASTIO_TOKEN"

   Python

   import os, requests
   
   BASE = f"https://{os.environ['ELASTIO_TENANT']}.app.elastio.com"
   HEADERS = {"Authorization": f"Bearer {os.environ['ELASTIO_TOKEN']}"}
   
   resp = requests.get(f"{BASE}/gateway/api/v1/health_check", headers=HEADERS, timeout=30)
   resp.raise_for_status()
   print(resp.json())

   PowerShell

   $Base = "https://$env:ELASTIO_TENANT.app.elastio.com"
   $Headers = @{ Authorization = "Bearer $env:ELASTIO_TOKEN" }
   Invoke-RestMethod -Uri "$Base/gateway/api/v1/health_check" -Headers $Headers

   A 200 response with a JSON body containing a status field means the tenant is reachable. A 401 means the token is missing, mistyped, expired or revoked. See Errors.

4. List your assets.

   GET /gateway/api/v2/assets returns the live inventory: every asset with its health, finding counts, latest hunts, tags and policy coverage. Filters are comma-separated lists; here you ask for AWS assets that have findings (infected) or are at risk, 25 at a time.

   GET

   /gateway/api/v2/assetsGet list of v2 assets (live inventory)

   Try it →
   cURL

   curl -G "https://$ELASTIO_TENANT.app.elastio.com/gateway/api/v2/assets" \
     -H "Authorization: Bearer $ELASTIO_TOKEN" \
     --data-urlencode "platform=aws" \
     --data-urlencode "health=infected,at_risk" \
     --data-urlencode "page_size=25"

   Python

   params = {"platform": "aws", "health": "infected,at_risk", "page_size": 25}
   resp = requests.get(f"{BASE}/gateway/api/v2/assets", headers=HEADERS, params=params, timeout=30)
   resp.raise_for_status()
   page = resp.json()
   
   for asset in page["data"]:
       print(asset["asset_id"], asset["asset_kind"], asset["asset_name"], asset["health"])

   PowerShell

   $page = Invoke-RestMethod -Uri "$Base/gateway/api/v2/assets?platform=aws&health=infected,at_risk&page_size=25" -Headers $Headers
   $page.data | Select-Object asset_id, asset_kind, asset_name, health

   The response has the matching assets in data, a total, and a pagination object:

   {
     "total": 42,
     "data": [
       {
         "asset_id": "0b6f3c1e-8a52-4c2e-9d1f-5e7a2b9c4d10",
         "asset_name": "web-prod-01",
         "asset_kind": "ec2_instance",
         "platform": "aws",
         "platform_details": { "account_id": "123456789012", "region": "us-east-1" },
         "health": "infected",
         "threats": { "malware": 0, "ransomware": 1, "encryption": 0, "filesystem_error": 0 },
         "…": "…"
       }
     ],
     "pagination": { "next_page_token": "eyJvZmZzZXQiOjI1fQ" }
   }

5. Fetch the next page.

   Pass pagination.next_page_token back as the next_page_token query parameter, with the same filters. When the response has no next_page_token, you have every result.

   cURL

   curl -G "https://$ELASTIO_TENANT.app.elastio.com/gateway/api/v2/assets" \
     -H "Authorization: Bearer $ELASTIO_TOKEN" \
     --data-urlencode "platform=aws" \
     --data-urlencode "health=infected,at_risk" \
     --data-urlencode "page_size=25" \
     --data-urlencode "next_page_token=eyJvZmZzZXQiOjI1fQ"

   Python

   assets = list(page["data"])
   token = (page.get("pagination") or {}).get("next_page_token")
   
   while token:
       resp = requests.get(
           f"{BASE}/gateway/api/v2/assets",
           headers=HEADERS,
           params={**params, "next_page_token": token},
           timeout=30,
       )
       resp.raise_for_status()
       page = resp.json()
       assets.extend(page["data"])
       token = (page.get("pagination") or {}).get("next_page_token")
   
   print(f"{len(assets)} assets")

   PowerShell

   $assets = @($page.data)
   $token = $page.pagination.next_page_token
   
   while ($token) {
       $t = [uri]::EscapeDataString($token)
       $page = Invoke-RestMethod -Uri "$Base/gateway/api/v2/assets?platform=aws&health=infected,at_risk&page_size=25&next_page_token=$t" -Headers $Headers
       $assets += $page.data
       $token = $page.pagination.next_page_token
   }
   "$($assets.Count) assets"

6. List open incidents.

   Incidents use offset pagination: limit (at most 20) and offset. status defaults to open, and severity takes a comma-separated list.

   GET

   /gateway/api/v2/incidentsList retained incident episodes

   Try it →
   cURL

   curl "https://$ELASTIO_TENANT.app.elastio.com/gateway/api/v2/incidents?status=open&severity=critical,high&limit=20" \
     -H "Authorization: Bearer $ELASTIO_TOKEN"

   Python

   params = {"status": "open", "severity": "critical,high", "limit": 20}
   resp = requests.get(f"{BASE}/gateway/api/v2/incidents", headers=HEADERS, params=params, timeout=30)
   resp.raise_for_status()
   body = resp.json()
   
   print(f"{body['total']} open incidents")
   for incident in body["data"]:
       print(incident["handle"], incident["finding"]["severity"], incident["finding"]["title"])

   PowerShell

   $body = Invoke-RestMethod -Uri "$Base/gateway/api/v2/incidents?status=open&severity=critical,high&limit=20" -Headers $Headers
   "$($body.total) open incidents"
   $body.data | ForEach-Object { "{0} {1} {2}" -f $_.handle, $_.finding.severity, $_.finding.title }

   {
     "total": 3,
     "data": [
       {
         "id": "7d2e9f40-1c3b-4a8e-b5d6-2f9a0c1e3b47",
         "handle": "INC-000012",
         "status": "open",
         "asset_id": "0b6f3c1e-8a52-4c2e-9d1f-5e7a2b9c4d10",
         "opened_at": "2026-10-11T08:14:03Z",
         "version": 1,
         "finding": {
           "id": "…",
           "class": "threat",
           "severity": "critical",
           "status": "open",
           "title": "…",
           "asset_name": "web-prod-01",
           "platform": "aws"
         },
         "…": "…"
       }
     ]
   }

   To get the next page, add offset=20, then offset=40, until offset reaches total.

Tip

Every operation in the API reference can also be sent from your browser. Connect your tenant in the API console and select Test Request.

Next steps

AuthenticationScope tokens to what your integration needs, and rotate them.

PaginationThe three pagination styles, with complete loops.

Assets and searchFilter and search your inventory.

Manage incidentsReview, assign, comment on and close incidents.