Stackurity Start free trial

API reference Ask Stackurity

Ask Stackurity

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

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

Role: a browser session

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

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Start an Ask Stackurity conversation

POST /ask/conversations

Role: a browser session

{}. 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

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Delete all of the caller's Ask Stackurity conversations

DELETE /ask/conversations

Role: a browser session

Deletes the caller's own conversations in this organisation; answers deleted

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

One of the caller's Ask Stackurity conversations

GET /ask/conversations/{id}

Role: a browser session

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

ParameterInTypeDescription
id requiredpathstring

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Delete one of the caller's Ask Stackurity conversations

DELETE /ask/conversations/{id}

Role: a browser session

404 for anyone else's (an organisation admin deletes everyone's with DELETE /ask/settings/conversations)

Parameters

ParameterInTypeDescription
id requiredpathstring

Responses

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

Feedback on an Ask Stackurity answer or conversation

POST /ask/conversations/{id}/feedback

Role: a browser session

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

ParameterInTypeDescription
id requiredpathstring

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXCreatedobject
4XXAn errorError
5XXAn errorError

Ask a question

POST /ask/conversations/{id}/messages

Role: a browser session

{"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

ParameterInTypeDescription
id requiredpathstring

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXServer-sent events: tool, text, reset, done, errorstring (text/event-stream)
4XXAn errorError
5XXAn errorError

Apply a change Ask Stackurity proposed

POST /ask/conversations/{id}/proposals/{pid}/apply

Role: a browser session

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

ParameterInTypeDescription
id requiredpathstring
pid requiredpathstring

Request body

application/json: object

Responses

StatusMeaningBody
2XXSuccess: proposalobject
4XXAn errorError
5XXAn errorError

Dismiss a change Ask Stackurity proposed

POST /ask/conversations/{id}/proposals/{pid}/dismiss

Role: a browser session

Closes an open proposal without applying it: proposal with status dismissed; 409 when it is not open

Parameters

ParameterInTypeDescription
id requiredpathstring
pid requiredpathstring

Request body

application/json: object

Responses

StatusMeaningBody
2XXSuccess: proposalobject
4XXAn errorError
5XXAn errorError

Start a connection Ask Stackurity handed off

POST /ask/conversations/{id}/proposals/{pid}/start

Role: a browser session

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

ParameterInTypeDescription
id requiredpathstring
pid requiredpathstring

Request body

application/json: object

Responses

StatusMeaningBody
2XXSuccess: proposalobject
4XXAn errorError
5XXAn errorError

Undo a change applied from Ask Stackurity

POST /ask/conversations/{id}/proposals/{pid}/undo

Role: a browser session

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

ParameterInTypeDescription
id requiredpathstring
pid requiredpathstring

Request body

application/json: object

Responses

StatusMeaningBody
2XXSuccess: proposalobject
4XXAn errorError
5XXAn errorError

Feedback on the Ask Stackurity panel itself

POST /ask/feedback

Role: a browser session

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

StatusMeaningBody
2XXCreatedobject
4XXAn errorError
5XXAn errorError

Accept the Ask Stackurity data notice

POST /ask/notice

Role: a browser session

{"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

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

Ask Stackurity settings and use

GET /ask/settings

Role: admin

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

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Turn Ask Stackurity on or off for the organisation

PUT /ask/settings

Role: admin

{"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

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Delete every Ask Stackurity conversation in the organisation

DELETE /ask/settings/conversations

Role: admin

Whoever had them; answers deleted (a count). Admins can delete conversations but never read them. Audited as ask.conversations_deleted

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Whether the caller can use Ask Stackurity now

GET /ask/status

Role: a browser session

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

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Ask Stackurity model calls of this organisation

GET /ask/usage/calls

Role: admin

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

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