API referencefor Strata 0.9.

Everything the interface does goes through this HTTP API, so a script can do it too: feed the map from an inventory, open proposals from a scanner, back up the history, run connectors on a schedule. This page lists every route. What stays stable from 1.0 on is in Compatibility.

Basics

• All routes are under the server’s own address, for example https://strata.example.lan/api/…. Bodies and answers are JSON (UTF-8).
• Writes (every method but GET and HEAD) must send both headers Content-Type: application/json and X-Requested-With: strata, or they are refused with 400. This is what stops another site from writing through a signed-in browser.
• Roles, from least to most: viewer (reads), contributor (proposes), approver (changes the map, reviews proposals, runs connectors), admin (accounts, tokens, connector settings, modules). A role can do everything the roles below it can. With READ_ONLY=true everybody is a viewer.
• Ids (IS, assets, proposals) are 1 to 120 characters among A-Z a-z 0-9 _ . : @ + ~ -.
• Batches: send X-Batch: <any id> on several writes to show them as one entry in the history, with X-Batch-Label: <URL-encoded label> as its title.
• Sizes: one IS or asset document is 512 KB at most; an import, a proposal or a file sent to a connector is MAX_IMPORT_MB (20 MB) at most. Bigger bodies answer 413.

Authentication

Every route but /healthz needs credentials, the same as the interface. Which ones work depends on how the server is set up (Accounts and roles).

For scripts, use an API token with the lowest role that does the job: a contributor token for a tool that should only propose, an approver token for one that writes. Repeated failed sign-ins answer 429 with a Retry-After header.

Answers and errors

A write that changes the map answers {"ok": true, "rev": N}, the map’s new revision. Other writes answer {"ok": true, …} with what they made. A refused request answers a JSON object with an error text meant for people, sometimes with more keys:

HTTP/1.1 409 Conflict
{"error": "Some items changed on the map since this proposal was prepared.", "conflicts": [...]}

Rely on the status and the keys, not on the wording of error, which can change.

Account

The map

The map is four parts: the IS documents (si, by id), the assets (by id), the links between IS (wan) and the shared Internet services (services). Their content is in Data format. Every change makes a new revision and an entry in the history.

Documents are replaced whole: to change one field, read the document, change it, send it back. To add a flow or a VLAN, change the IS document (si.flows, si.vlans).

curl -H "Authorization: Bearer $STRATA_TOKEN" \
  -H 'Content-Type: application/json' -H 'X-Requested-With: strata' \
  -X PUT https://strata.example.lan/api/assets/srv-erp-01 \
  -d '{"site":"lyon","name":"srv-erp-01","type":"server","vlan":"v-lyo-20","ip":"10.20.0.20",
       "os":"RHEL 8","role":"ERP","crit":3,
       "vulns":[{"id":"CVE-2021-44228","title":"Log4Shell","cvss":10,"sev":"crit"}]}'

History

Proposals

A proposal is a set of changes that an approver merges into the map, or not. Its changes are {si: {id: doc}, assets: {id: doc}, wan?: [...], services?: [...]}, where a document set to null deletes it. Its status goes draft → submitted → approved or rejected; a submitted proposal can be withdrawn back to draft, and editing a rejected one makes it a draft again.

# a scanner that proposes instead of writing (contributor token)
curl -H "Authorization: Bearer $STRATA_TOKEN" \
  -H 'Content-Type: application/json' -H 'X-Requested-With: strata' \
  -X POST https://strata.example.lan/api/proposals \
  -d '{"title":"Weekly scan, Lyon","siteId":"lyon",
       "changes":{"assets":{"lyo-old-ftp":null}}}'

Connectors

Connector routes answer 404 when connectors are off (CONNECTORS=false). A connector’s id is cyberwatch, glpi, phpipam, paloalto or the id of an installed module.

A run never writes the map: it opens proposals (one per IS), which an approver reviews. run is {id, at, by, file, ok, summary, error, proposals: [{id, title, siteId}], ms}.

Module store

Accounts, tokens, sessions

Live events

GET /api/events (viewer) is a Server-Sent Events stream. It sends the current revision on connection, then:

curl -N -H "Authorization: Bearer $STRATA_TOKEN" https://strata.example.lan/api/events

Treat the events as a signal to read again, not as the data itself: their content may grow.

Sign-in pages

These are for browsers, not scripts.

Data format

An export file, GET /api/export and the body of POST /api/import share one format. Only si and assets are required; format and version say what wrote the file.

{
  "format": "strata", "version": 3, "exportedAt": "2026-10-26T09:00:00.000Z",
  "si":       { "<IS id>": { IS document } },
  "assets":   { "<asset id>": { asset document } },
  "wan":      [ { link } ],
  "services": [ { Internet service } ]
}

The export of a single IS (Export this IS (JSON)) adds "scope": "si" and holds that IS, its assets and the shared services. The interface imports it by replacing that IS only; POST /api/import always replaces the whole map, so to load one IS from a script, send its documents with PUT /api/si/{id} and PUT /api/assets/{id}.

IS document

Asset document

src on a vulnerability, application or contact names the connector it came from; entries without one were typed by hand.

Links and Internet services

The quickest way to see real documents is an Export JSON of the demo.

Module API

Connector modules have their own contract, described in full in MODULES.md:

• The manifest, strata-module.json, with "strataModule": 1: id, name, version, main, minStrata, permissions, fields, live, file.
• The code exports test(cfg, ctx) and run(cfg, ctx); ctx holds state, file, log and sdk; run resolves with {proposals, summary, report}.
• The SDK, ctx.sdk: request, expectOk, assetIndex, siteFor, vlanForIp, the IP, XML and text helpers, ConnectorError.
• The store index, index.json with "strataRegistry": 1: each module’s manifest summary, its package url and sha256.

Compatibility

Strata follows Semantic Versioning. Before 1.0, a minor version (0.9 → 0.10) may still break things; the changelog says how to upgrade each time. From 1.0 on, every 1.x version keeps the following working.

What stays stable in 1.x

• The routes on this page under /api/, their methods, the roles they need, the request fields they accept and the answer fields they return.
• Authentication: Basic for local accounts, Bearer stk_… tokens, the write headers Content-Type: application/json and X-Requested-With: strata, X-Batch and X-Batch-Label.
• Status codes and the error key of refusals (not its wording).
• The data format: the fields listed in Data format keep their meaning. Every export file written by an earlier version (version 3 and below) keeps importing; a 1.x version may write a higher version number, and still reads the lower ones.
• The module API: a module written for "strataModule": 1 keeps running, with the same ctx and SDK helpers; a store index with "strataRegistry": 1 keeps being read.
• The event names change, proposals, connectors, and rev in change.

What may change in a minor version

• New routes, optional request fields, answer fields, document fields, event names, roles’ abilities, SDK helpers. Write clients that ignore fields they do not know, and send back the fields they did not change: the server keeps them.
• The interface, the sign-in pages, the texts of error, log lines, files in DATA_DIR (use the API, not the files), anything not on this page.
• Security fixes: if a behaviour is a security hole, it is closed in a patch version even if a script relied on it, and the changelog says so.

Deprecation

1. Something to be removed is first marked Deprecated in the changelog, with what to use instead.
2. It keeps working for at least one more minor version after that (deprecated in 1.3: still there in 1.4, removed in 1.5 at the earliest). Where it can, the server logs a warning when it is used.
3. Removal happens in a minor version, under Removed and Upgrading in the changelog. Only a major version (2.0) may remove something without deprecating it first.