Quick Start: API Access

The Stairwell API lets you programmatically search objects, manage assets, create YARA rules, and integrate Stairwell data into your existing workflows. This guide covers generating a token and making your first request.

1. Create an authentication token

1. Log in at app.stairwell.com
2. Click the Settings icon in the left menu
3. Select Auth tokens under the Organization section
4. Click Generate Token and choose API/CLI token
5. Give the token a descriptive name (e.g., "API - threat hunting script")
6. Click Generate and copy the token immediately -- it will not be displayed again

2. Find your environment ID

1. In Settings, select the Environments tab
2. Your environment ID is displayed on the environment detail page

You will need this ID for API calls scoped to your environment.

3. Make your first API call

Use the token and environment ID to query an object by its SHA-256 hash:

curl -s \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  "https://app.stairwell.com/v1/environments/YOUR_ENVIRONMENT_ID/objects/OBJECT_SHA256"

Replace YOUR_API_TOKEN, YOUR_ENVIRONMENT_ID, and OBJECT_SHA256 with your actual values. A successful response returns the object's metadata, Mal-Eval score, and associated sightings.

4. Explore the API reference

The full Stairwell API reference is available at docs.stairwell.com/reference. It covers all available endpoints including objects, assets, YARA rules, opinions, threat reports, and environments.

Security note: Treat your API token like a password. Do not commit tokens to source control or share them in plain text. If a token is compromised, revoke it immediately in Settings > Auth Tokens.