Stackurity Start free trial

API reference Instance administration

Instance administration

56 operations. Base URL https://app.stackurity.dev/api/v1 on Stackurity Cloud; see authentication.

Ask Stackurity on this server

GET /admin/ask

Role: instance admin

configured, provider, default_model, effort, global_spend_cap_micros and spend_this_month_micros across every organisation

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Ask Stackurity model calls on this server

GET /admin/ask/calls

Role: instance admin

Every organisation's Ask Stackurity model calls on this server. items: one per model call, newest first, with id, created_at, workspace_id, user_id, conversation_id (null once deleted), kind (answer, summary or triage, the small call that asks whether a short follow-up says the last answer was wrong), model, prompt_version, input_tokens, output_tokens, cache_read_tokens, cache_write_tokens, cost_micros (millionths of a US dollar), latency_ms, tool_calls, tool_names, history_turns_sent, summary_used, stop_reason, error_code, request_id, step_up_reason (why this answer moved to a stronger model: complex, rephrased, dissatisfied, not_found, tool_error, thumbs_down, stopped; empty when it did not) and stepped_from (the model it moved from). Metadata only: never a question, an answer or tool results. Kept 90 days (then daily totals, kept two years). format=csv returns the same as a CSV file

Parameters

ParameterInTypeDescription
sincequerystring (date-time)Calls at or after this time (RFC 3339)
untilquerystring (date-time)Calls before this time (RFC 3339)
limitqueryintegerDefault 1000. From 1 to 10000.
before_idqueryintegerNext page: calls with a smaller id
formatquerystringOne of json, csv. Default json.

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Ask Stackurity feedback, every organisation

GET /admin/ask/feedback

Role: instance admin, or a feedback review token

Newest first: items (id, workspace_id, user_id, conversation_id, message_id, kind (explicit or implicit), rating, category, scope, text, consent, snapshot (with consent, until 90 days), prompt_version, model, usage_call_id, page_path, viewport, status, resolution_notes, created_at, updated_at) and next_before when there may be more. Implicit signals (category): rephrased, not_found, tool_error, stopped, abandoned. Never visible to an organisation's admins

Parameters

ParameterInTypeDescription
statusquerystringnew, triaged, fixed or wontfix
kindquerystringexplicit or implicit
ratingquerystringup or down
categoryquerystringa category or signal
workspace_idquerystringone organisation
sincequerystringa date (2006-01-02) or RFC 3339 time
prompt_versionquerystringthe system prompt's version
beforequerystringan id: rows older than it (paging)
limitquerystring1 to 200 (default 50)

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

One Ask Stackurity feedback row

GET /admin/ask/feedback/{id}

Role: instance admin, or a feedback review token

As in the list

Parameters

ParameterInTypeDescription
id requiredpathstring

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Triage Ask Stackurity feedback

PATCH /admin/ask/feedback/{id}

Role: instance admin, or a feedback review token

status (new, triaged, fixed, wontfix) and/or resolution_notes (up to 4,000 characters). Audited

Parameters

ParameterInTypeDescription
id requiredpathstring

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Feedback review tokens

GET /admin/ask/review-tokens

Role: instance admin

items: id, name, prefix, created_by, created_at, expires_at, last_used_at, revoked_at; never the secret

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Make a feedback review token

POST /admin/ask/review-tokens

Role: instance admin

name, expires_in_days (0: never; up to 366). 201 with token and secret (shown once, prefix stkfr_). The token is not tied to an organisation and works only on GET /admin/ask/feedback, GET /admin/ask/feedback/{id} and PATCH /admin/ask/feedback/{id}: every other request with it is 403

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXCreatedobject
4XXAn errorError
5XXAn errorError

Revoke a feedback review token

DELETE /admin/ask/review-tokens/{id}

Role: instance admin

At once

Parameters

ParameterInTypeDescription
id requiredpathstring

Responses

StatusMeaningBody
2XXSuccess (usually 204 No Content)no body
4XXAn errorError
5XXAn errorError

Errors people hit, across workspaces

GET /admin/client-errors

Role: instance admin

Error reports across every workspace, for Platform health: new (errors seen for the first time, or again after 7 days, in the last 24 hours) and top (the 20 most frequent in the last 7 days). Each has fingerprint, kind (client: the dashboard; server: a 5xx answer or panic of the API), route, method, api_route, status, code, name, top_frame, first_seen, last_seen, new_since, count, workspaces (counted, never named), versions, browsers and the latest scrubbed sample. Also enabled (false with STACKURITY_CLIENT_ERRORS=off) and retention_days (install.md#error-reports)

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

The free self-hosted keys issued (hosted edition)

GET /admin/community-keys

Role: instance admin Stackurity Cloud only

Stackurity Cloud (hosted) only. total, emails, last_30_days and the newest items

Parameters

ParameterInTypeDescription
limitqueryinteger

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

What Stackurity cannot check, across workspaces

GET /admin/coverage-gaps

Role: instance admin

What Stackurity cannot check across every active workspace, as counts of assets and workspaces by type: unread_files (files no built-in reader or installed stack pack reads, by kind such as hex:mix.lock), no_vulnerability_source (components with unsupported coverage, by package type and reason, vendor builds by repository) and no_lifecycle (products no lifecycle source tracks, release lines missing from the data, runtimes and operating systems with no lifecycle product), with workspaces, assets and the lifecycle overlay_version. Names no workspace, asset, path or package (compatibility.md)

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

List the feedback queue

GET /admin/feedback

Role: instance admin or feedback triage token

Items newest first; status (comma-separated), before (a reference) and limit (up to 200) narrow it. Also counts per status and storage (used_bytes, max_bytes). See feedback-queue.md

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

List feedback triage tokens

GET /admin/feedback-tokens

Role: instance admin

Tokens for the triage agent, with prefix, expires_at, last_used_at and revoked_at. See feedback-queue.md

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Create a feedback triage token

POST /admin/feedback-tokens

Role: instance admin

name and days (1 to 90, default 30). The secret (stkfb_…) is in the answer once. It reads items and attachments and writes status and notes under /admin/feedback, and nothing else. See feedback-queue.md

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Revoke a feedback triage token

DELETE /admin/feedback-tokens/{id}

Role: instance admin

Revokes the token at once. See feedback-queue.md

Parameters

ParameterInTypeDescription
id requiredpathstring

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Preview the emails sent to people who sent feedback

GET /admin/feedback/email-templates

Role: instance admin or feedback triage token

The released and won't-fix emails rendered with sample text (name, subject, body) and enabled. See feedback-queue.md

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

List feedback attachments waiting for the virus scan

GET /admin/feedback/scan/pending

Role: instance admin or feedback scanner token

Pending attachments: id, storage_key, size, sha256. See feedback-queue.md

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Report a virus scan verdict

POST /admin/feedback/scan/{aid}

Role: instance admin or feedback scanner token

result clean or infected (with signature). See feedback-queue.md

Parameters

ParameterInTypeDescription
aid requiredpathstring

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Read a feedback item

GET /admin/feedback/{id}

Role: instance admin or feedback triage token

id is FB-123 or 123. The item with triage_notes, its attachments (without their files) and events. See feedback-queue.md

Parameters

ParameterInTypeDescription
id requiredpathstring

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Change a feedback item's status and notes

PATCH /admin/feedback/{id}

Role: instance admin or feedback triage token

Any of status, resolution (shown to the sender; required for wont_fix), triage_notes (replace) or note (append a dated paragraph), link (a pull request or issue under github.com/stackurity), duplicate_of (a reference; required for duplicate), fixed_in. See feedback-queue.md

Parameters

ParameterInTypeDescription
id requiredpathstring

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Delete a feedback item

DELETE /admin/feedback/{id}

Role: instance admin

Deletes an item (spam, abuse) with its attachment files and history. See feedback-queue.md

Parameters

ParameterInTypeDescription
id requiredpathstring

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Get a download link for an attachment

POST /admin/feedback/{id}/attachments/{aid}/link

Role: instance admin or feedback triage token

A signed link to /feedback-attachments/{id} valid for ten minutes, with expires_at, name, content_type and size. 410 when retention deleted the file. See feedback-queue.md

Parameters

ParameterInTypeDescription
id requiredpathstring
aid requiredpathstring

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Free plan dry run: organisations it would change (hosted edition)

GET /admin/free-plan/preview

Role: instance admin Stackurity Cloud only

Stackurity Cloud (hosted) only. items: exactly the organisations turning on the Free plan (STACKURITY_CLOUD_FREE_PLAN) would change (none whose trial or plan already ended), with workspace_id, name, billing status now and after, read_only, projects, project_limit, read_only_projects, monitored and asset_limit; kept for the operator's own organisations, which it leaves unchanged; free_plan_on; paid_limits_from (STACKURITY_CLOUD_PAID_LIMITS_FROM, null: never). 400 no_free_plan when the plans list no Free plan. Read only

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Platform health across workspaces

GET /admin/health

Role: instance admin

Platform health across workspaces: status (ok, warning, critical), problems (each with last_success, last_error, scope, next_step and docs; objects are named only for the caller's active workspace), background tasks with their last success and error, job counts by kind and state, jobs that failed in the last 24 hours, notification deliveries by channel kind and state, the age of the oldest due notification and failing_channels (install.md)

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

The installation's licence

GET /admin/license

Role: instance admin

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Install a licence key

PUT /admin/license

Role: instance admin

Install a licence key or the free key, checked offline

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Remove the licence key

DELETE /admin/license

Role: instance admin

Remove the licence key or free key; a self-hosted server then waits for a key again

Responses

StatusMeaningBody
2XXSuccess (usually 204 No Content)no body
4XXAn errorError
5XXAn errorError

Start getting the free key from Stackurity Cloud

POST /admin/license/link

Role: instance admin

"Get a free key": a one-time state bound to this browser session (15 minutes) and the Stackurity Cloud address the browser goes to. The server makes no request. Needs STACKURITY_BASE_URL

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Install the free key Stackurity Cloud sent back

POST /admin/license/link/claim

Role: instance admin

{"key", "state"}: the key from the return page's fragment, with the state from POST /admin/license/link. The state works once, within 15 minutes, in the session that made it; the key must verify offline as a free Community key

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Installed stack packs

GET /admin/packs

Role: instance admin

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Install a stack pack from the catalogue

POST /admin/packs/install

Role: instance admin

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Upload and install a stack pack archive

POST /admin/packs/upload

Role: instance admin

Request body

application/octet-stream, required: string

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Enable, disable or update a stack pack

PATCH /admin/packs/{id}

Role: instance admin

Parameters

ParameterInTypeDescription
id requiredpathstring

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Remove a stack pack

DELETE /admin/packs/{id}

Role: instance admin

Parameters

ParameterInTypeDescription
id requiredpathstring

Responses

StatusMeaningBody
2XXSuccess (usually 204 No Content)no body
4XXAn errorError
5XXAn errorError

Roll a stack pack back to its previous version

POST /admin/packs/{id}/rollback

Role: instance admin

Parameters

ParameterInTypeDescription
id requiredpathstring

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Trial report: cloud organisations by sign-up week (hosted edition)

GET /admin/trials

Role: instance admin Stackurity Cloud only

Stackurity Cloud (hosted) only. Every organisation that signed up, by the week it signed up (cohorts, totals), and orgs with trial dates, state (trialing, converted, expired, cancelled), billing_status, first asset, last sign-in, collection, agent check-in and API use, active_7d, active_30d, flags (never_activated, went_quiet, trial_ended_not_converted) and contact (who signed up: name, email, sign_ins; billing: billing_email, billing_legal_name, billing_country; ref). excluded lists the workspaces left out. Read only

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Extend one organisation's trial (hosted edition)

PUT /admin/trials/{id}

Role: instance admin Stackurity Cloud only

Stackurity Cloud (hosted) only. trial_ends_at (RFC 3339, in the future and within a year); applied at once and audited cloud.trial_extended

Parameters

ParameterInTypeDescription
id requiredpathstring

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Workspaces with their members, assets and limits

GET /admin/workspaces

Role: instance admin

Workspaces with member_count, asset_count, monitored and asset_limit (null: none). PATCH takes name, disabled, plan and asset_limit (-1 removes the limit; see asset-limits.md)

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Create a workspace and name its first admin

POST /admin/workspaces

Role: instance admin

Workspaces with member_count, asset_count, monitored and asset_limit (null: none). PATCH takes name, disabled, plan and asset_limit (-1 removes the limit; see asset-limits.md)

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Rename, disable or set the plan, limits, read-only state and report mode of a workspace

PATCH /admin/workspaces/{id}

Role: instance admin

Workspaces with member_count, asset_count, monitored and asset_limit (null: none). PATCH takes name, disabled, plan, asset_limit and project_limit (-1 removes a limit), read_only with read_only_reason, report_mode (full or trial) and plan_limits (replaces them; {} removes them); see asset-limits.md

Parameters

ParameterInTypeDescription
id requiredpathstring

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Plan and billing of the organisation (hosted edition)

GET /billing

Role: admin Stackurity Cloud only

Stackurity Cloud (hosted) only. Status (trial, trial_ended, awaiting_payment, active, past_due, halted, cancelling, cancelled), plans, limits, read-only and deletion dates, billing_enabled and contact_url

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Cancel the plan at the end of the period (hosted edition)

POST /billing/cancel

Role: admin Stackurity Cloud only

Stackurity Cloud (hosted) only. A browser session only. Then the organisation becomes read-only

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Change who the tax invoices are made out to (hosted edition)

PUT /billing/details

Role: admin Stackurity Cloud only

Stackurity Cloud (hosted) only. legal_name, address, state (GST state code, India), tax_id (GSTIN or EU VAT number), checked for the organisation's billing country, which does not change. Answers the billing. 409 before the first subscription

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Invoices of the organisation (hosted edition)

GET /billing/invoices

Role: admin Stackurity Cloud only

Stackurity Cloud (hosted) only. Invoices of this organisation's subscriptions

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Download a tax invoice as PDF (hosted edition)

GET /billing/invoices/{id}/pdf

Role: admin Stackurity Cloud only

Stackurity Cloud (hosted) only. The tax invoice of the organisation's invoice id (inv_...) as application/pdf, as an attachment. 404 when it has none: not paid yet, paid before tax invoices came on, or waiting for billing details

Parameters

ParameterInTypeDescription
id requiredpathstring

Responses

StatusMeaningBody
2XXSuccessstring (binary) (application/pdf)
4XXAn errorError
5XXAn errorError

Subscribe to or change a plan (hosted edition)

POST /billing/subscribe

Role: admin Stackurity Cloud only

Stackurity Cloud (hosted) only. plan_id, extra_assets, country (asked once; decides the currency), replace. Answers billing, payment_url and message. An upgrade the payment provider applies only at the end of the period (a card mandate it changes then) applies now and message says what is added to the next invoice. 409 replace_required for a subscription whose plan the payment provider cannot change (UPI, e-mandate, an Indian card): asked again with replace: true it is replaced by the bigger plan, paid on payment_url. A browser session only. 503 billing_off while billing is off; 409 while a payment is being confirmed

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Receive one feedback item (the website relay)

POST /feedback-queue/intake

Role: the website relay (intake key)

Only on the server that runs the feedback queue (STACKURITY_FEEDBACK_QUEUE_DIR). multipart/form-data: an item part (JSON: kind, description, email, page, browser, viewport, version, edition, hosting, source), then up to three attachment parts. Needs X-Stackurity-Feedback-Key. 201 with ref and the sender's status token; 413 too large, 415 not an accepted type, 507 attachment storage full. See feedback-queue.md

Request body

multipart/form-data, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Look up feedback status by token (the website relay)

POST /feedback-queue/status

Role: the website relay (intake key)

{"items": [{"ref", "token"}]} (up to 50); answers each item's public status, resolution (once decided), fixed_in and updated_at, or unknown when the token does not match. Needs X-Stackurity-Feedback-Key. See feedback-queue.md

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

The organisation's own single sign-on (hosted edition)

GET /sso

Role: admin Stackurity Cloud only

Stackurity Cloud (hosted) only. available (the plan includes it), config (provider, attribute mapping, version, tested_version, test_result, enabled, require_sso, link_existing), service_provider (entity_id, acs_url, metadata_url, login_url), domains, owner_id

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Save the organisation's SAML identity provider (hosted edition)

PUT /sso

Role: admin Stackurity Cloud only

Stackurity Cloud (hosted) only. idp_metadata_url (https) or idp_metadata (XML; neither keeps the saved one), label, email_attribute, name_attribute, groups_attribute, role_map, default_role, link_existing. The metadata is checked at once. A save is a new version and switches single sign-on off until a test passes. 402 plan_required without the plan

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Remove the organisation's single sign-on (hosted edition)

DELETE /sso

Role: admin Stackurity Cloud only

Stackurity Cloud (hosted) only. Removes the provider and switches single sign-on off

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Claim an email domain for single sign-on (hosted edition)

POST /sso/domains

Role: admin Stackurity Cloud only

Stackurity Cloud (hosted) only. domain. Answers the TXT record_name and record_value that prove it

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Remove a claimed domain (hosted edition)

DELETE /sso/domains/{id}

Role: admin Stackurity Cloud only

Stackurity Cloud (hosted) only. Sign-ins with the domain's addresses stop

Parameters

ParameterInTypeDescription
id requiredpathstring

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Verify a claimed domain by its DNS TXT record (hosted edition)

POST /sso/domains/{id}/verify

Role: admin Stackurity Cloud only

Stackurity Cloud (hosted) only. 409 when another organisation verified the domain first

Parameters

ParameterInTypeDescription
id requiredpathstring

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Switch the organisation's single sign-on on or off (hosted edition)

PUT /sso/state

Role: admin Stackurity Cloud only

Stackurity Cloud (hosted) only. enabled, require_sso, existing_tokens. Switching on needs a passed test of the current version and a verified domain; requiring it needs it on. The owner can always sign in with a password. When require_sso goes from false to true, existing_tokens is required: keep leaves API tokens and AI assistant connections working; revoke revokes, in this organisation, members' API tokens and AI assistant connections and unlinks their Slack accounts in the same transaction, and the response's revoked gives the counts. Agents' and CI jobs' tokens and the owner's are kept. Sent at any other time, existing_tokens is refused (400)

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Whether a newer release is available, and the release check's state

GET /updates

Role: instance admin

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError