API reference Ask Stackurity
Ask Stackurity
The in-app assistant: conversations, questions (server-sent events) and the organisation's settings. See docs/ai-assistants.md.
The caller's Ask Stackurity conversations
GET /ask/conversations
The caller's own conversations in this organisation, the latest first: id, title, model, created_at, updated_at, expires_at (30 days after creation)
Responses
Start an Ask Stackurity conversation
POST /ask/conversations
{}. Answers the conversation (201), with the organisation's model and the project chosen in the switcher. 404 not_configured, 403 ask_disabled, 402 plan_required or read_only when it cannot be used
Request body
application/json, required: object
Responses
Delete all of the caller's Ask Stackurity conversations
DELETE /ask/conversations
Deletes the caller's own conversations in this organisation; answers deleted
Responses
One of the caller's Ask Stackurity conversations
GET /ask/conversations/{id}
conversation and its messages as the caller saw them (role, text, page, stop_reason, created_at); no tool data; and proposals, the changes Ask proposed in it with their state (proposed, applied, dismissed, expired, failed, undone) and the question_seq of the question each answered. 404 for anyone else's, an organisation admin's included
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Responses
Delete one of the caller's Ask Stackurity conversations
DELETE /ask/conversations/{id}
404 for anyone else's (an organisation admin deletes everyone's with DELETE /ask/settings/conversations)
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Responses
Feedback on an Ask Stackurity answer or conversation
POST /ask/conversations/{id}/feedback
seq (the answer, for scope answer), rating (up or down), category (wrong, misunderstood, incomplete, slow, wrong_data, formatting, idea, other), scope (answer, the default; chat; ui: the panel itself), text (what they expected, up to 2,000 characters), consent (share the conversation with the Stackurity team: with it a snapshot of the messages' visible text, credentials and email addresses removed, is kept 90 days; without it only the category, text and metadata), page_path (no query), viewport (WIDTHxHEIGHT). 201 with id. The conversation must be the caller's own (404 otherwise); 30 an hour per person
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Request body
application/json, required: object
Responses
Ask a question
POST /ask/conversations/{id}/messages
{"text", "page": {"kind": "finding" | "asset" | "component" | "fix_group", "id"}}. The answer streams as server-sent events: tool (what is being read), text (a piece of the answer), reset (drop the text so far), proposal (a change Ask proposed, for the person to apply or dismiss; nothing is changed), proposals_dropped (the turn is answered again: drop its proposals), done (stop_reason, questions_used, questions_limit, message) or error (code, message). Before the stream: 409 notice_required, 429 quota_reached, busy or rate_limited (10 a minute and 60 an hour per person), and the status errors of POST /ask/conversations
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Request body
application/json, required: object
Responses
Apply a change Ask Stackurity proposed
POST /ask/conversations/{id}/proposals/{pid}/apply
The person's click on Apply: runs the proposed write tool's confirm path as the caller, through the same API, role and project checks as the dashboard, and answers proposal (status applied, link, can_undo). A browser session only (API tokens and connected assistants are refused), for a proposal of the caller's own conversation (404 otherwise), while the organisation lets Ask propose changes (403 proposals_off). Each proposal applies once (409 proposal_applied, proposal_dismissed, proposal_failed) and within 15 minutes (410 proposal_expired). When what the change covers changed since the preview, nothing is applied: 409 changed with the new preview in error.proposal, to apply again. The API's own refusal (403 for a role too low) is returned as it is, with the proposal marked failed. The activity log names the caller "(via Ask Stackurity)". A server hand-off (tool connect, args.kind server) creates a one-server install code as the caller and answers install (code, enrollment) too; the code is in this response only
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string | |
pid required | path | string |
Request body
application/json: object
Responses
Dismiss a change Ask Stackurity proposed
POST /ask/conversations/{id}/proposals/{pid}/dismiss
Closes an open proposal without applying it: proposal with status dismissed; 409 when it is not open
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string | |
pid required | path | string |
Request body
application/json: object
Responses
Start a connection Ask Stackurity handed off
POST /ask/conversations/{id}/proposals/{pid}/start
Records that the caller clicked a hand-off's button or link (tool connect, any kind but server): proposal with status started. The dashboard then starts the service's own flow, or opens its setup page; the connection is made by that flow's endpoints. Once, within 15 minutes of the hand-off: 409 proposal_started after that, 410 proposal_expired, 400 not_started for a server hand-off or a change, 403 proposals_off
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string | |
pid required | path | string |
Request body
application/json: object
Responses
Undo a change applied from Ask Stackurity
POST /ask/conversations/{id}/proposals/{pid}/undo
Reverses an applied change that has a clean reverse (can_undo: a snooze, whose issues are reopened, or a project rename, back to the old name), once, within 15 minutes of applying it, through the same API and checks: proposal with status undone
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string | |
pid required | path | string |
Request body
application/json: object
Responses
Feedback on the Ask Stackurity panel itself
POST /ask/feedback
From a panel with no conversation yet: scope must be ui; otherwise as POST /ask/conversations/{id}/feedback (no snapshot)
Request body
application/json, required: object
Responses
Accept the Ask Stackurity data notice
POST /ask/notice
{"version"}: the notice version from /ask/status; 409 notice_changed for an older one. Audited as ask.notice_accepted
Request body
application/json, required: object
Responses
Ask Stackurity settings and use
GET /ask/settings
enabled, configured, provider, model, question_limit, question_period, spend_cap_micros, questions_this_month, spend_this_month_micros (millionths of a US dollar), consent_version, the current consent wording's version, and propose_changes (Ask may propose changes for people to apply). Never anyone's conversations
Responses
Turn Ask Stackurity on or off for the organisation
PUT /ask/settings
{"enabled": true, "consent_version": "…"} turns it on: consent_version is the version of the consent wording the administrator ticked and confirmed in the dashboard's consent dialog (consent_version from GET /ask/settings). Without it: 400 consent_required; an older version: 409 consent_outdated; from an API token or a connected assistant: 403 (consent is a signed-in person's). Who agreed, when and to which version is stored and audited as ask.consent. {"enabled": false} turns it off, audited as ask.settings. {"propose_changes": true | false} (alone, or with enabled) turns "Ask may propose changes" on or off, audited as ask.settings
Request body
application/json, required: object
Responses
Delete every Ask Stackurity conversation in the organisation
DELETE /ask/settings/conversations
Whoever had them; answers deleted (a count). Admins can delete conversations but never read them. Audited as ask.conversations_deleted
Responses
Whether the caller can use Ask Stackurity now
GET /ask/status
available, and when not, reason (not_configured, ask_disabled, plan_required, read_only, spend_cap) and message; notice_version and notice_accepted; questions_used, questions_limit (null: no limit), question_period (month or total), resets_at
Responses
Ask Stackurity model calls of this organisation
GET /ask/usage/calls
This organisation's Ask Stackurity model calls. 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. |