REST APIs

Stairwell publishes more than one REST surface, and picking the right one is the first decision. Use the v1 API for files, assets, YARA rules, threat reports, and opinions: it is the current surface and it is where new endpoints appear. Use Network Intelligence, served under /v2, for hostname and IP address intelligence. The long term support surfaces are older endpoints kept stable for integrations already built on them, not somewhere to start. The Backstory surface is beta and carries no compatibility promise. All of them live on https://app.stairwell.com except file intake, and all of them take the same auth token.

Which API should I use?

Start from the object you are working with.

What you want	Surface	Reference
Look up a file, list files matching a filter, read its sightings, variants, relationships, opinions, tags, or comments	v1, under `/v1`	Stairwell V1 HTTP APIs
Read or change an asset, list the assets in an environment, archive or sleep or wake one	v1, under `/v1`	Stairwell V1 HTTP APIs
Create, read, or update YARA rules, run a rule, list what it matched	v1, under `/v1`	Stairwell V1 HTTP APIs
Read threat reports and their indicators, or ask which of them match your environment	v1, under `/v1`	Stairwell V1 HTTP APIs
Read trigger matches, set opinions, manage groups	v1, under `/v1`	Stairwell V1 HTTP APIs
Resolution history for a hostname, what resolves to an IP address, WHOIS for an IP or an ASN, cloud provider lookups, hostname and URL normalization	Network Intelligence, under `/v2`	Stairwell Network Intelligence
Upload files into Stairwell from your own code	File Intake API	Long Term Support APIs
Run a Backstory investigation and fetch its report	Backstory, under `/backstory/v1beta1`	Stairwell Backstory (Beta)

Each reference in the right-hand column is a section of the API Reference on this site, generated from the surface's own definition, so it is the endpoint-by-endpoint truth. This page exists to get you to the right one; it does not restate them.

What is the v1 API?

The current Stairwell REST surface, on https://app.stairwell.com under /v1. If you are building something new against Stairwell's file, asset, rule, and report data, this is it.

Two properties are worth knowing before you read the reference, because they shape how the whole surface reads.

It is resource-oriented. Endpoints name resources rather than actions, and a resource's name is its canonical identifier: an object is named by its hash, an asset by its asset ID. Store those names, not URLs you assembled.

Lists are filtered with CEL and paginated with tokens. GET /v1/objects/metadata takes a filter expression in Stairwell's query language and returns pages of matching objects. pageSize defaults to 50 and 50 is also the maximum, so anything that reads a large result set is a loop over pageToken rather than one big request. See CEL Query Language for writing the filter, which is the same language behind the search boxes in the app.

One shape to expect. Where an endpoint returns something expensive, you get a small preview inline with a flag saying whether there is more, and a separate endpoint for the paginated whole. Object relationships work this way: the metadata response carries a handful with a hasMore flag, and GET /v1/objects/{object}/relationships gives you all of them. Bulk list endpoints leave the expensive enrichments out entirely so they stay fast, which means a field you saw on a single-object response may be absent from a list.

Quick Start: API Access walks the first authenticated request end to end.

What is Network Intelligence, and why is it a separate API?

Stairwell's hostname, IP address, and ASN intelligence, served on the same host under /v2. It is separate because it answers questions about network identifiers rather than about your files, and it is scoped and versioned on its own.

What it covers:

Hostnames. The addresses a name has resolved to over time, filtered by record type and by time interval, one hostname at a time or in bulk.
IP addresses. Enrichment for an address, the hostnames that resolve to it, and its WHOIS record.
ASNs. WHOIS by autonomous system number, optionally restricted to particular regional registries.
Cloud providers. Whether an address belongs to a known provider, and the published ranges for a set of providers.
Utilities. Hostname and URL normalization, and the registrable domain (eTLD+1) for a name, singly or in bulk. These are the boring ones and they save the most time, because everyone who joins network data to their own data writes them badly at least once.

Network Intelligence explains what this data is and what it is good for. Use it before the reference if the resolution history is new to you.

What are the long term support APIs?

Two older endpoints kept working for integrations already built on them.

The File Intake API is how you upload files into Stairwell from your own code. It is a two-step flow: you post the file's metadata and expected SHA-256 to https://http.intake.app.stairwell.com/v2021.05/upload, and the response either tells you Stairwell already has the file, in which case you are done, or hands back a signed upload URL and the form fields to use. That preflight is the point of the design: an environment that has already seen a file never uploads it again. Its reference page carries working shell and Python examples.

If you do not need to build this yourself, do not. swell objects upload performs exactly this flow, handles hashing and parallelism, and is one binary with no dependencies. See swell.

An older detonation endpoint under /v202112 is documented in the same category. Newer replacements for it live under /v1, listed under Objects in the V1 reference, so a new integration should use those.

The rule for this whole category: if you are choosing, do not choose these. They exist so that integrations written years ago keep working.

What is the Backstory API, and can I rely on it?

It runs Backstory investigations from your own code, under /backstory/v1beta1. You submit an indicator, poll the job, and fetch the verdict, the report, the recommendations, or the graph state.

It is a beta surface, and that is a real caveat rather than a formality: routes and response shapes can change. Changes are announced in the changelog, so the way to depend on it is to read that rather than to discover a change from a failing integration. The Backstory API covers the workflow and the fields that deserve a decision rather than a default.

How do I authenticate?

One bearer token, generated in the Stairwell app, on every surface:

curl -H "Authorization: Bearer $STAIRWELL_TOKEN" \
  "https://app.stairwell.com/v1/objects/<sha256>/metadata"

Generate the token under Settings, then Auth tokens under the Organization section. Quick Start: API Access has the full procedure and the first request to make with it.

Treat the token as a credential. It is shown once, it carries your access, and it belongs in a secret store rather than in a repository, a scheduled job's command line, or a support ticket.

What is scoped to an environment, and what is not?

Most of it. Assets, YARA rules, threat reports, groups, and trigger matches are addressed under an environment, and your token reaches the environments your account is authorized for and no others. Object lookups, hostname and IP intelligence, and the utilities are not environment-scoped in the URL, but what you can see through them still follows the same authorization.

This matters for a practical reason. An integration that works for you and returns nothing for a colleague is usually not a bug in the integration; it is two accounts with different environment access. See Environments for what an environment is and why nearly every call needs one.

What should I read next?

Quick Start: API Access, to make your first authenticated request.
CEL Query Language, for the filter expressions the list endpoints take.
MCP Server, if what you actually want is to ask questions of this data in natural language rather than write a client.
swell, if a command line tool would do the job instead of a client you maintain.