Actions: Preview, Then Confirm

An Action is a bulk operation Provet runs for a signed-in user after the user has seen and confirmed what it will do, for example sending debt letters to a list of clients. Every Action works the same way:

Preview. Your application sends the request. Provet checks it against live data and answers with what would happen. Nothing is written.
Show the preview to the user. The user confirms it, or not.
Confirm. Your application confirms that preview. Provet runs exactly what the preview showed, as that user.
Follow the run until it is done or failed.

The request and response bodies of each Action are in the schema, under the tag Action: <key>.

Access

Only OAuth tokens issued to a user work. An Action runs as that user, with that user’s permissions. Legacy API keys and tokens without a user (client credentials) get 403 with code user_token_required; a request without credentials gets 401. See Authentication via OAuth 2.0.
The token needs the restapi and actions scopes: request them together, as scope=restapi actions. actions alone is refused with the OAuth error invalid_scope, because the rest of the REST API authorizes by the user’s permissions, not by scope. A token without actions gets 403 with code insufficient_scope on every endpoint below. The scope is not self-service: it is enabled for your application when you agree on Actions with Provet (see Adding an Application in Provet).
Each Action is switched on separately. An Action that is not enabled for the organization answers 403 with code feature_disabled. The user also needs the permissions of the page the Action mirrors; otherwise the answer is 403 with code permission_denied.
The department is the user’s active department in Provet, the one the user last selected in the app. Your application does not choose it.

GET actions/ lists every Action and tells you, in enabled, whether this user may run it now. It applies the same checks as the Action’s own endpoints, so use it instead of trying a preview.

Endpoints

All paths are under /<provet_id>/api/0.1/.

Call	Request	Response
`GET actions/`		Every Action: `key`, `summary`, `enabled`, `is_async`, `max_targets`, `preview_ttl_seconds`, `preview_url`, `runs_url`
`POST actions/<key>/preview/`	The Action’s parameters	`preview_id`, `expires_at`, `target_count`, `skipped` (targets left out, with a reason) and the Action’s `details`
`POST actions/<key>/runs/`	`{"preview_id": "...", "conversation_id": "..."}`; `conversation_id` is optional: your own reference, up to 64 letters, digits, `_` or `-`	The run. `202` when the work continues in the background, `201` when it finished in the request, `200` when this preview was already confirmed (the same run again)
`GET action_runs/`, `GET action_runs/{id}/`	Filters: `action_type`, `status`	The user’s own runs: `status` (`running`, `done`, `failed`), `error_code`, `linked` (the object the run created), `result`

Previews

A preview_id is valid for preview_ttl_seconds (10 minutes by default) and can be confirmed once, by the same user, for the same Action.
Confirm runs what the preview showed. It never recomputes the list. If the data changed since the preview in a way that matters (for example, a client paid), confirm answers 400 with code preview_stale: preview again and show the user the new result.
A preview with nothing to do answers 400 with preview_empty. More targets than max_targets answer 400 with too_many_targets.

Retries

Confirm is safe to retry with the same preview_id:

200 with the run: this preview was already confirmed. Nothing ran twice.
409 with confirm_in_progress: the first confirm is still starting the run. Wait a moment and retry.
400 with preview_not_found: the preview expired, was refused, or never existed. Preview again.

Following a run

Poll GET action_runs/{id}/ until status is done or failed. When a run fails, error_code says why:

start_failed: the work could not be started.
task_failed: the background work failed. Part of it may be done; the result counts, when present, say how much.
timed_out: the work did not report back in time.

Runs stay readable while an Action is switched off, so a started run can always be followed to its end.

Errors and rate limits

Errors carry {"detail": "...", "code": "..."}. Branch on code, which is stable; detail is for people and may change.

Rate limits apply per user, not per token: every token of the same user, in every application, shares one budget. By default, per minute: 30 previews and 10 confirms per Action, 60 list calls and 120 run lookups. A request over the limit gets 429 with Retry-After. See Rate limit.