API reference Instance administration
Instance administration
Ask Stackurity on this server
GET /admin/ask
configured, provider, default_model, effort, global_spend_cap_micros and spend_this_month_micros across every organisation
Responses
Ask Stackurity model calls on this server
GET /admin/ask/calls
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
| Parameter | In | Type | Description |
|---|---|---|---|
since | query | string (date-time) | Calls at or after this time (RFC 3339) |
until | query | string (date-time) | Calls before this time (RFC 3339) |
limit | query | integer | Default 1000. From 1 to 10000. |
before_id | query | integer | Next page: calls with a smaller id |
format | query | string | One of json, csv. Default json. |
Responses
Ask Stackurity feedback, every organisation
GET /admin/ask/feedback
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
| Parameter | In | Type | Description |
|---|---|---|---|
status | query | string | new, triaged, fixed or wontfix |
kind | query | string | explicit or implicit |
rating | query | string | up or down |
category | query | string | a category or signal |
workspace_id | query | string | one organisation |
since | query | string | a date (2006-01-02) or RFC 3339 time |
prompt_version | query | string | the system prompt's version |
before | query | string | an id: rows older than it (paging) |
limit | query | string | 1 to 200 (default 50) |
Responses
One Ask Stackurity feedback row
GET /admin/ask/feedback/{id}
As in the list
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Responses
Triage Ask Stackurity feedback
PATCH /admin/ask/feedback/{id}
status (new, triaged, fixed, wontfix) and/or resolution_notes (up to 4,000 characters). Audited
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Request body
application/json, required: object
Responses
Feedback review tokens
GET /admin/ask/review-tokens
items: id, name, prefix, created_by, created_at, expires_at, last_used_at, revoked_at; never the secret
Responses
Make a feedback review token
POST /admin/ask/review-tokens
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
Revoke a feedback review token
DELETE /admin/ask/review-tokens/{id}
At once
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Responses
Errors people hit, across workspaces
GET /admin/client-errors
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
The free self-hosted keys issued (hosted edition)
GET /admin/community-keys
Stackurity Cloud (hosted) only. total, emails, last_30_days and the newest items
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
limit | query | integer |
Responses
What Stackurity cannot check, across workspaces
GET /admin/coverage-gaps
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
List the feedback queue
GET /admin/feedback
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
List feedback triage tokens
GET /admin/feedback-tokens
Tokens for the triage agent, with prefix, expires_at, last_used_at and revoked_at. See feedback-queue.md
Responses
Create a feedback triage token
POST /admin/feedback-tokens
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
Revoke a feedback triage token
DELETE /admin/feedback-tokens/{id}
Revokes the token at once. See feedback-queue.md
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Responses
Preview the emails sent to people who sent feedback
GET /admin/feedback/email-templates
The released and won't-fix emails rendered with sample text (name, subject, body) and enabled. See feedback-queue.md
Responses
List feedback attachments waiting for the virus scan
GET /admin/feedback/scan/pending
Pending attachments: id, storage_key, size, sha256. See feedback-queue.md
Responses
Report a virus scan verdict
POST /admin/feedback/scan/{aid}
result clean or infected (with signature). See feedback-queue.md
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
aid required | path | string |
Request body
application/json, required: object
Responses
Read a feedback item
GET /admin/feedback/{id}
id is FB-123 or 123. The item with triage_notes, its attachments (without their files) and events. See feedback-queue.md
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Responses
Change a feedback item's status and notes
PATCH /admin/feedback/{id}
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
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Request body
application/json, required: object
Responses
Delete a feedback item
DELETE /admin/feedback/{id}
Deletes an item (spam, abuse) with its attachment files and history. See feedback-queue.md
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Responses
Get a download link for an attachment
POST /admin/feedback/{id}/attachments/{aid}/link
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
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string | |
aid required | path | string |
Responses
Free plan dry run: organisations it would change (hosted edition)
GET /admin/free-plan/preview
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
Platform health across workspaces
GET /admin/health
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
The installation's licence
GET /admin/license
Responses
Install a licence key
PUT /admin/license
Install a licence key or the free key, checked offline
Request body
application/json, required: object
Responses
Remove the licence key
DELETE /admin/license
Remove the licence key or free key; a self-hosted server then waits for a key again
Responses
Start getting the free key from Stackurity Cloud
POST /admin/license/link
"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
Install the free key Stackurity Cloud sent back
POST /admin/license/link/claim
{"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
Installed stack packs
GET /admin/packs
Responses
Install a stack pack from the catalogue
POST /admin/packs/install
Request body
application/json, required: object
Responses
Upload and install a stack pack archive
POST /admin/packs/upload
Request body
application/octet-stream, required: string
Responses
Enable, disable or update a stack pack
PATCH /admin/packs/{id}
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Request body
application/json, required: object
Responses
Remove a stack pack
DELETE /admin/packs/{id}
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Responses
Roll a stack pack back to its previous version
POST /admin/packs/{id}/rollback
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Request body
application/json, required: object
Responses
Trial report: cloud organisations by sign-up week (hosted edition)
GET /admin/trials
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
Extend one organisation's trial (hosted edition)
PUT /admin/trials/{id}
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
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Request body
application/json, required: object
Responses
Workspaces with their members, assets and limits
GET /admin/workspaces
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
Create a workspace and name its first admin
POST /admin/workspaces
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
Rename, disable or set the plan, limits, read-only state and report mode of a workspace
PATCH /admin/workspaces/{id}
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
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Request body
application/json, required: object
Responses
Plan and billing of the organisation (hosted edition)
GET /billing
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
Cancel the plan at the end of the period (hosted edition)
POST /billing/cancel
Stackurity Cloud (hosted) only. A browser session only. Then the organisation becomes read-only
Request body
application/json, required: object
Responses
Change who the tax invoices are made out to (hosted edition)
PUT /billing/details
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
Invoices of the organisation (hosted edition)
GET /billing/invoices
Stackurity Cloud (hosted) only. Invoices of this organisation's subscriptions
Responses
Download a tax invoice as PDF (hosted edition)
GET /billing/invoices/{id}/pdf
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
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Responses
Subscribe to or change a plan (hosted edition)
POST /billing/subscribe
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
Receive one feedback item (the website relay)
POST /feedback-queue/intake
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
Look up feedback status by token (the website relay)
POST /feedback-queue/status
{"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
The organisation's own single sign-on (hosted edition)
GET /sso
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
Save the organisation's SAML identity provider (hosted edition)
PUT /sso
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
Remove the organisation's single sign-on (hosted edition)
DELETE /sso
Stackurity Cloud (hosted) only. Removes the provider and switches single sign-on off
Responses
Claim an email domain for single sign-on (hosted edition)
POST /sso/domains
Stackurity Cloud (hosted) only. domain. Answers the TXT record_name and record_value that prove it
Request body
application/json, required: object
Responses
Remove a claimed domain (hosted edition)
DELETE /sso/domains/{id}
Stackurity Cloud (hosted) only. Sign-ins with the domain's addresses stop
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Responses
Verify a claimed domain by its DNS TXT record (hosted edition)
POST /sso/domains/{id}/verify
Stackurity Cloud (hosted) only. 409 when another organisation verified the domain first
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Responses
Switch the organisation's single sign-on on or off (hosted edition)
PUT /sso/state
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
Whether a newer release is available, and the release check's state
GET /updates