GET	/api/posture/summary
GET	/api/posture/servers
GET	/api/posture/findings
GET	/api/posture/servers/:serverId
GET	/api/posture/servers/:serverId/metrics
GET	/api/posture/servers/:serverId/expected-ports
POST	/api/posture/servers/:serverId/expected-ports
DELETE	/api/posture/servers/:serverId/expected-ports/:entryId
GET	/api/posture/export/fields
POST	/api/posture/export
POST	/api/posture/findings/:id/mute
POST	/api/posture/findings/:id/unmute
POST	/api/posture/findings/:id/acknowledge
GET	/api/posture/settings
PUT	/api/posture/settings
GET	/api/posture/alert-rules
GET	/api/posture/alert-rules/:id
POST	/api/posture/alert-rules
PUT	/api/posture/alert-rules/:id
DELETE	/api/posture/alert-rules/:id
GET	/api/posture/inventory/services
GET	/api/posture/inventory/listeners
GET	/api/posture/inventory/facets

Summary

GET/api/posture/summary

Authentication: bearer token.
Permission: posture.read.

Query parameters

Name	Type	Required	Notes
customerId	string	No
environment	string	No

curl -X GET "https://shellius.example.com/api/posture/summary" \
  -H "Authorization: Bearer $SHELLIUS_TOKEN"

200 OK

{ "success": true, "data": { … } }

Servers

GET/api/posture/servers

Authentication: bearer token.
Permission: posture.read.

Query parameters

Name	Type	Required	Notes
state	string	No	One of reporting, stale, not_installed, not_applicable.
page	number	No	Default 1. At least 1.
limit	number	No	Default 25. 1–100.

curl -X GET "https://shellius.example.com/api/posture/servers" \
  -H "Authorization: Bearer $SHELLIUS_TOKEN"

200 OK

{ "success": true, "data": { … } }

Findings

GET/api/posture/findings

Authentication: bearer token.
Permission: posture.read.

Query parameters

Name	Type	Required	Notes
severity	string	No
status	string	No
section	string	No	One of open, expected, acknowledged, muted, resolved.
customerId	string	No
environment	string	No
serverId	string	No
page	number	No	Default 1. At least 1.
limit	number	No	Default 25. 1–100.

curl -X GET "https://shellius.example.com/api/posture/findings" \
  -H "Authorization: Bearer $SHELLIUS_TOKEN"

200 OK

{ "success": true, "data": { … } }

Retrieve posture

GET/api/posture/servers/:serverId

Authentication: bearer token.
Permission: posture.read.

Path parameters

Name	Type	Notes
serverId	string

curl -X GET "https://shellius.example.com/api/posture/servers/{serverId}" \
  -H "Authorization: Bearer $SHELLIUS_TOKEN"

200 OK

{ "success": true, "data": { … } }

Servers metrics

GET/api/posture/servers/:serverId/metrics

Authentication: bearer token.
Permission: posture.read.

Path parameters

Name	Type	Notes
serverId	string

Query parameters

Name	Type	Required	Notes
from	date	No	ISO 8601.
to	date	No	ISO 8601.
bucket	string	No	Default auto.

curl -X GET "https://shellius.example.com/api/posture/servers/{serverId}/metrics" \
  -H "Authorization: Bearer $SHELLIUS_TOKEN"

200 OK

{ "success": true, "data": { … } }

Servers expected ports

GET/api/posture/servers/:serverId/expected-ports

Authentication: bearer token.
Permission: posture.read.

Path parameters

Name	Type	Notes
serverId	string

curl -X GET "https://shellius.example.com/api/posture/servers/{serverId}/expected-ports" \
  -H "Authorization: Bearer $SHELLIUS_TOKEN"

200 OK

{ "success": true, "data": { … } }

Servers expected ports

POST/api/posture/servers/:serverId/expected-ports

Authentication: bearer token.
Permission: posture.expected_ports.

Path parameters

Name	Type	Notes
serverId	string

Request body

Name	Type	Required	Notes
entries	array	Yes	One of tcp, udp, any. Default any. 1–65535.

curl -X POST "https://shellius.example.com/api/posture/servers/{serverId}/expected-ports" \
  -H "Authorization: Bearer $SHELLIUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "entries": "tcp"
  }'

200 OK

{ "success": true, "data": { … } }

Delete posture

DELETE/api/posture/servers/:serverId/expected-ports/:entryId

Authentication: bearer token.
Permission: posture.expected_ports.

Path parameters

Name	Type	Notes
serverId	string
entryId	string

curl -X DELETE "https://shellius.example.com/api/posture/servers/{serverId}/expected-ports/{entryId}" \
  -H "Authorization: Bearer $SHELLIUS_TOKEN"

200 OK

{ "success": true, "data": { … } }

Export fields

GET/api/posture/export/fields

Export — posture.export, audited.

Authentication: bearer token.
Permission: posture.export.

curl -X GET "https://shellius.example.com/api/posture/export/fields" \
  -H "Authorization: Bearer $SHELLIUS_TOKEN"

200 OK

{ "success": true, "data": { … } }

Export

POST/api/posture/export

POST, not GET: the field selection and a bulk server list do not belong in a URL, and an export is a recorded action rather than a cacheable read.

Authentication: bearer token.
Permission: posture.export.

Request body

Name	Type	Required	Notes
dataset	string	Yes	One of findings, listeners.
format	string	No	Default csv.
bundle	string	No	Default single.
fields	array	No	Default []. At most 64.
filters	object	No	One of open, muted, resolved, all. 0–2000.

curl -X POST "https://shellius.example.com/api/posture/export" \
  -H "Authorization: Bearer $SHELLIUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "dataset": "findings"
  }'

Returns a file or plain text, not the JSON envelope.

Findings mute

POST/api/posture/findings/:id/mute

Finding lifecycle — posture.mute, audited.

Authentication: bearer token.
Permission: posture.mute.

Path parameters

Name	Type	Notes
id	string

Request body

Name	Type	Required	Notes
days	number	No	1–3650.
until	date	No	ISO 8601.
reason	string	Yes	1–1000 characters.

curl -X POST "https://shellius.example.com/api/posture/findings/{id}/mute" \
  -H "Authorization: Bearer $SHELLIUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "…"
  }'

200 OK

{ "success": true, "data": { … } }

Findings unmute

POST/api/posture/findings/:id/unmute

Authentication: bearer token.
Permission: posture.mute.

Path parameters

Name	Type	Notes
id	string

curl -X POST "https://shellius.example.com/api/posture/findings/{id}/unmute" \
  -H "Authorization: Bearer $SHELLIUS_TOKEN"

200 OK

{ "success": true, "data": { … } }

Findings acknowledge

POST/api/posture/findings/:id/acknowledge

Authentication: bearer token.
Permission: posture.mute.

Path parameters

Name	Type	Notes
id	string

curl -X POST "https://shellius.example.com/api/posture/findings/{id}/acknowledge" \
  -H "Authorization: Bearer $SHELLIUS_TOKEN"

200 OK

{ "success": true, "data": { … } }

Settings

GET/api/posture/settings

Settings — posture.settings.

Authentication: bearer token.
Permission: posture.settings.

curl -X GET "https://shellius.example.com/api/posture/settings" \
  -H "Authorization: Bearer $SHELLIUS_TOKEN"

200 OK

{ "success": true, "data": { … } }

Settings

PUT/api/posture/settings

Authentication: bearer token.
Permission: posture.settings.

Request body

Name	Type	Required	Notes
enabled	boolean	No
collectIntervalSeconds	number	No	1–86400.
snapshotRetentionDays	number	No	1–365.
metricRetentionHours	number	No	1–8760.
findingRetentionDays	number	No	1–3650.
expectedPublicPorts	array	No	At most 200.

curl -X PUT "https://shellius.example.com/api/posture/settings" \
  -H "Authorization: Bearer $SHELLIUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false,
    "collectIntervalSeconds": 0,
    "snapshotRetentionDays": 0
  }'

200 OK

{ "success": true, "data": { … } }

Alert rules

GET/api/posture/alert-rules

Alert rules — posture.settings.

Authentication: bearer token.
Permission: posture.settings.

curl -X GET "https://shellius.example.com/api/posture/alert-rules" \
  -H "Authorization: Bearer $SHELLIUS_TOKEN"

200 OK

{ "success": true, "data": { … } }

Retrieve posture

GET/api/posture/alert-rules/:id

Authentication: bearer token.
Permission: posture.settings.

Path parameters

Name	Type	Notes
id	string

curl -X GET "https://shellius.example.com/api/posture/alert-rules/{id}" \
  -H "Authorization: Bearer $SHELLIUS_TOKEN"

200 OK

{ "success": true, "data": { … } }

Alert rules

POST/api/posture/alert-rules

Authentication: bearer token.
Permission: posture.settings.

Request body

Name	Type	Required	Notes
name	string	Yes	1–200 characters.
isActive	boolean	No	Default true.
severities	array	No	Default [].
codes	array	No	Default []. At most 100.
customerIds	array	No	Default [].
environments	array	No	Default [].
recipientRoles	array	No	Default []. At most 100.
recipientGroupId	string	No	May be null.
recipientUserIds	array	No	Default [].
channels	array	No	Default ['inapp'].
mode	string	No	One of immediate, digest. Default immediate.
notifyOnResolve	boolean	No	Default false.
throttleMinutes	number	No	Default 0. 0–10080.
escalateAfterHours	number	No	1–720. May be null.
escalateToGroupId	string	No	May be null.

curl -X POST "https://shellius.example.com/api/posture/alert-rules" \
  -H "Authorization: Bearer $SHELLIUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "…"
  }'

201 Created

{ "success": true, "data": { … } }

Update posture

PUT/api/posture/alert-rules/:id

Authentication: bearer token.
Permission: posture.settings.

Path parameters

Name	Type	Notes
id	string

curl -X PUT "https://shellius.example.com/api/posture/alert-rules/{id}" \
  -H "Authorization: Bearer $SHELLIUS_TOKEN"

200 OK

{ "success": true, "data": { … } }

Delete posture

DELETE/api/posture/alert-rules/:id

Authentication: bearer token.
Permission: posture.settings.

Path parameters

Name	Type	Notes
id	string

curl -X DELETE "https://shellius.example.com/api/posture/alert-rules/{id}" \
  -H "Authorization: Bearer $SHELLIUS_TOKEN"

200 OK

{ "success": true, "data": { … } }

Inventory services

GET/api/posture/inventory/services

One row per distinct service.

Authentication: bearer token.
Permission: posture.read.

Query parameters

Name	Type	Required	Notes
q	string	No	At most 200 characters.
proto	string	No	At most 8 characters.
reachability	string	No	At most 16 characters.
ownerKind	string	No	At most 32 characters.
port	number	No	0–65535.
portMin	number	No	0–65535.
portMax	number	No	0–65535.
serverId	string	No
customerId	string	No
environment	string	No	At most 32 characters.
serviceKey	string	No	At most 160 characters.
state	string	No	One of running, stopped, internal, exposed.
hasFindings	boolean	No
page	number	No	At least 1.
limit	number	No	1–200.

curl -X GET "https://shellius.example.com/api/posture/inventory/services" \
  -H "Authorization: Bearer $SHELLIUS_TOKEN"

200 OK

{ "success": true, "data": { … } }

Inventory listeners

GET/api/posture/inventory/listeners

The flat port list across the fleet.

Authentication: bearer token.
Permission: posture.read.

Query parameters

Name	Type	Required	Notes
q	string	No	At most 200 characters.
proto	string	No	At most 8 characters.
reachability	string	No	At most 16 characters.
ownerKind	string	No	At most 32 characters.
port	number	No	0–65535.
portMin	number	No	0–65535.
portMax	number	No	0–65535.
serverId	string	No
customerId	string	No
environment	string	No	At most 32 characters.
serviceKey	string	No	At most 160 characters.
state	string	No	One of running, stopped, internal, exposed.
hasFindings	boolean	No
page	number	No	At least 1.
limit	number	No	1–200.

curl -X GET "https://shellius.example.com/api/posture/inventory/listeners" \
  -H "Authorization: Bearer $SHELLIUS_TOKEN"

200 OK

{ "success": true, "data": { … } }

Inventory facets

GET/api/posture/inventory/facets

Distinct filter values, in scope.

Authentication: bearer token.
Permission: posture.read.

curl -X GET "https://shellius.example.com/api/posture/inventory/facets" \
  -H "Authorization: Bearer $SHELLIUS_TOKEN"

200 OK

{ "success": true, "data": { … } }