Skip to main content
Read this after choosing the SDK, CLI, HTTP API, or Platform. Every path creates the same durable Run: one assessment record holding its approved scope, progress, findings, and lifecycle. This page covers the decisions each path leaves to you.

​
Choose an integration path

Pick the path that matches where your team already owns credentials, persistence, and review. These are parallel paths, not shortcuts to one another. Use the SDK or HTTP API for application-owned records and unattended work, and the CLI when a member is operating the assessment directly. Whichever you choose, the approved target, the durable Run ID, and the review record stay the same.

​
Plan an authorized assessment

Start from organization permission and approved targets. Define the business purpose, systems in scope, model, and Guardrails before creating a Run, and record that intent with the assessment so a reviewer can later distinguish authorized work from a similar-looking target. Create one Run for one coherent objective. A Run can cover several approved targets, but combining unrelated objectives makes evidence, assignment, and remediation harder to review. Broader scope reduces coordination overhead; narrower scope makes each finding’s next action clearer. If any of these changes materially, record the new decision before creating a new Run. Do not repurpose an in-progress assessment by sending broad guidance, and do not reuse a target from a different organization context. Decide where these will persist before you create anything: The SDK and HTTP examples write small files to make this boundary visible. Replace them with the persistence your application already uses, and never keep a Run ID only in process memory.

​
Create, then confirm the record

Save the Run ID before waiting for results. A create response can be interrupted after the service accepted it but before your caller records the answer, which leaves the caller unsure while the Run exists and runs normally. If your application already has an ID, read that Run instead of submitting another assessment. Then read the Run back to confirm its status and target list. The ID is opaque and grants nothing on its own; every request is still authorized in the caller’s organization context.

​
Observe progress without losing evidence

Events are ordered observations of a durable Run. Process an event, store its sequence, then move the checkpoint:
  1. Read the event and associate it with the saved Run ID.
  2. Perform your evidence-handling step.
  3. Persist that event’s sequence only after the step succeeds.
  4. On reconnect, request events strictly after the saved sequence.
Saving the checkpoint first can silently skip unprocessed work. Never saving makes the same evidence look new after every interruption. This ordering also lets a later process tell unhandled evidence apart from evidence already reviewed.

​
Review findings and direct the next action

Findings carry severity, title, description, remediation, and available evidence. Review them in the assessment’s authorized context: confirm the affected target, preserve supporting evidence, prioritize remediation, and record an assigned next action. Findings are evidence for a human risk decision, not the decision itself. A completed Run may contain no findings; record that outcome with its scope and completion status rather than treating absence as an integration failure. Keep the same review record for every finding: When an assessment needs direction, send guidance that stays inside its approved scope, and prefer a specific reviewable request over a broad change of purpose. If necessary work falls outside the approved target or Guardrails, stop and obtain authorization for a separate assessment.

​
Pause, resume, and cancel deliberately

Each lifecycle action expresses a decision about the assessment. None of them is a way to repair a local timeout. Resuming does not re-evaluate target approval, so confirm the approved scope still applies first. If an action returns INVALID_RUN_STATE, another transition already occurred: read the Run and choose an action valid for the observed status rather than sending a second transition.

​
Recover from an interruption

One rule covers every failure on this page: a local failure changes what your caller knows, not what the Run is doing. A request deadline, an AbortSignal, a closed terminal, or a dropped event connection tells you nothing about the durable record. Read the saved Run before deciding anything. Keep the request ID whenever a service error provides one. It lets a support conversation identify the failing request without exposing credentials.

​
Hand off an assessment

When another operator or service takes over, provide the Run ID, the last processed event sequence, the approved scope, the latest observed status, and the current remediation decision. Do not hand off credentials. The receiving operator must use their own authorized session or application credential to read the durable record, which is also what keeps the audit trail meaningful.