Start an AI tool run from the widget
POST/api/widget/tools/runs
PUBLIC endpoint (anonymous visitors, NO staff auth) — doc 97 §13. Starts a
run of a tool profile the workspace offers in the widget (the profiles in
the session config's ai_tools). The run belongs to the contact in the
verified session token, never to anything the client names; the visitor
must hold a live session (the check that stands in for a captcha).
Consent comes BEFORE the upload: when the profile requires it, send back
the consent.version the config gave you (the sha256 of the exact text
shown). A missing or stale version is refused with 409 consent_required and the current text and version; nothing is stored.
The run goes through the same gates as one from a conversation (plan,
workspace switch, the profile offered in the widget and on this page's
host, kill switch, per-person/day and per-workspace limits, wallet). A
gate refusal is still 201 — the run exists, in state refused, with
the profile's own message. Starting is throttled per session, per IP and
per widget key (429).
Request
Responses
- 201
- 403
- 404
- 409
- 413
- 422
- 429
The run (pending, or refused by a gate).
Missing / invalid session, a blocked visitor or a banned IP.
Unknown widget key, or the profile is not offered in the widget (on this host) — code = surface_off.
Consent to the current text was not given (code = consent_required).
The photo is larger than the limit (image_too_large).
Not an image (bad_image), an unknown format (unknown_format), or a validation error.
Rate limit exceeded.
Response Headers
Request quota for the current window.
Remaining requests in the current window.
Seconds to wait before retrying.