Run an action

POST /v1/action runs an action. POST /v1/actions, with an s, creates one. The two paths differ by one character and do opposite things.

An action turns a finished audit into a document — the grounds for an appeal, a plain-language summary, a letter. You name the audit — either by sending it back or by naming the job it came from — name the action, and get a jobId; the work is asynchronous exactly as POST /v1/analyze is, and you collect the result from GET /v1/jobs/:jobId under result.generatedDocument.

A run is spent before the request is validated. As on the analysis call, the counter increments before the handler looks at the body, so a 400 here has still cost a run.

Request body

The audit is named one of two ways, and exactly one of them: clinicalData is the audit fed back in verbatim — the object GET /v1/jobs/:jobId returned as result.clinicalData — and jobId is the analysis job it came from, which we then read it off ourselves. A request carrying both is a 400, and so is one carrying neither. actionType is an id from GET /v1/actions.

If you already send a jobId here, check it. Until now this route had no such field, so one sent beside clinicalData was ignored and the action ran off the audit you pasted. It is a second name for the audit now, and sending both is a 400 — the two can name different audits, and before this only one of them was ever going to run. Drop whichever of the two you like; they produce the same action. A jobId that could not name a job at all — a number rather than a string, or one containing / — is also a 400.

jobId is there so you do not have to carry the report. An audit of a long investigation is a large object, and an integration that only ever passes it from one of our calls to the next gains nothing by holding it — an AI assistant driving this API through a tool call cannot realistically hold it at all. Naming the job is the same request without the payload:

curl -X POST https://api.granska.cloud/v1/action \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jobId": "b2b_a1b2c3d4",
    "actionType": "action_overklagande",
    "profileId": "lss_utredning"
  }'

The two forms produce the same action from the same audit: we read the job through the same projection GET /v1/jobs/:jobId answers through, so neither route sees anything the other does not.

With one exception, and it is the reason to send the audit rather than name it. Leaving a finding out of the action — include_in_action below — is a mark you make on the audit you send. Naming a jobId sends no audit, so there is nowhere to put the mark: we read the stored audit, which carries every finding the analysis produced. There is no error to expect here, because there is no field to reject; the action is simply written from all of them. An integration that excludes findings has to send clinicalData.

The job has to still be there. Reading a job does not delete it and does not extend its life either — scheduled cleanup normally removes a job and its audit between 15 and 30 minutes after the job's last update when a successful run reaches that job within its per-run capacity. Two missed four-minute sweep runs fit within thirty minutes, including execution, only if the next run succeeds and reaches the job. Further failed runs or a backlog beyond that run's capacity can delay removal beyond thirty minutes and require later successful runs. Once the job is removed, jobId answers 404 NOT_FOUND and the audit you kept is the only copy you can still get through the API: send it as clinicalData. A job of yours that has not finished, one that failed, and an action job answer 409 CONFLICT. A job your credential did not start answers 403 FORBIDDEN: another organisation's job, one another API client of yours started, or one a person started in the web application or the API tester.

profileId is required — the same id you passed to POST /v1/analyze to produce the audit. A request without it is a 400. It used to be optional, and the engine then worked out which profile produced the audit by matching the document type: an organisation with more than one profile for the same document type could silently land on the wrong one, which means the wrong legal framework and possibly the wrong output language. Named explicitly, the profile is validated against your licences the same way the analysis call validates it — and GET /v1/actions?profileId= lists the actions that profile is written for, so the actionType you send here can be chosen from that list rather than from all of them.

The findings decide which profile the action is written from, and profileId has to agree with them. Every finding an analysis delivers carries profile_id, naming the granskningsprofil whose review produced it, and finding_id beside it — see the fields on a finding. Both are recognised here, and the action resolves its profiles from the tags rather than from the profileId you send. Send back the findings the analysis delivered together with the profileId it ran under and nothing changes. Send a profileId naming a different profile than the findings do — or findings from two different reviews in one payload — and the call answers 400 BAD_REQUEST naming both sides, rather than quietly writing the document from one of them. An audit produced before those fields existed carries no tags and is accepted on profileId alone, exactly as before.

Fields the audit schema does not recognise are ignored, so an audit you have annotated on your own side can be sent back as it stands.

Leaving a finding out of the action. Set include_in_action: false on any entry in deduplicated_flaws or consolidated_strengths and the action is written as if that finding did not exist. The field is optional and absent means included, so an audit sent back unchanged behaves exactly as it always has. It is a mark on the audit in the request body, so it is available on the clinicalData form only, never on the jobId one.

Filtering the arrays yourself is not the same thing, and that is why the field exists. The audit carries executive_summary, which names and counts the findings in prose, so an excluded finding would still be described to the generator by a payload whose arrays no longer hold it. So whenever at least one entry is excluded, executive_summary is left out of the generation too; it is not rewritten or replaced. is_flawless is recomputed from the findings that remain whenever you exclude one, so an exclusion can never leave it contradicting them. Exclude nothing and it is passed through exactly as you sent it.

Excluding a finding costs nothing — no second analysis, no extra generation, no quota. Nothing about the audit itself changes: GET /v1/jobs/:jobId keeps returning every finding the analysis produced, and only the action is scoped.

The fields marking which text is the audited document's — quoted_locator and fenced_verbatim, see which words are the document's — are recognised here, so an audit sent back exactly as it was received keeps its markings instead of having them quietly dropped. Both are optional: an audit produced before they existed is accepted unchanged. The generation fences the whole audit again under a fresh nonce of its own, so a stale fence in what you send changes nothing.

An audit stored before the citation rework is rejected

clinicalData is validated against the same schema an analysis produces. A result saved before the citation fields were reworked lacks primary_authority_type and primary_label, both required, and the call answers 400 BAD_REQUEST with the validation error in message.

There is no translation path, and there will not be one. primary_label has to be a label the engine issued during the very analysis that produced the finding, and those labels no longer exist for an analysis that has been delivered and deleted. An old result cannot be recomputed into the new shape — it can only be produced again.

What to do: run the document through POST /v1/analyze again and send the fresh result here. If you hold a queue of saved audits waiting for action generation, drain it before upgrading. A result produced after the rework can be sent back unchanged, as always — the break is across one release boundary, in one direction, once.

The same applies to the stored results in GET /v1/examples/:profileId, which are also from before the rework.

Diagnostics and webhooks

includeDiagnostics adds this action's own diagnostic output — the model, the action type, the agent name, the generator's raw output and token usage — under result.diagnostics on the finished job. It is scoped to this action and is not the broader internal debug bundle. It works in production.

webhookUrl and webhookSecret behave exactly as they do on the analysis call, down to the payload, the retry schedule and the signature. See Webhooks.

Errors