Public documentation

Cloud Upload API

The CLI uploads findings to workbench through the Cloud upload API.

Most users should use:

roleplay upload latest
roleplay upload all

This reference is for users integrating custom upload flows.

Authentication

Uploads require a workbench project and project-scoped API key created in onboarding or Monitor.

Pass the key through:

ROLEPLAY_API_KEY=<key>

Or:

roleplay upload latest --api-key <key>

Supported modes:

Sanitized mode is the default.

Top-level fields:

Field	Required	Description
`projectId`	yes	workbench project ID.
`mode`	no	Upload mode. Defaults to `sanitized_findings`.
`source`	no	`ci` or `local`. Defaults to `local`.
`branch`	no	Branch name.
`commit`	no	Commit SHA.
`buildUrl`	no	CI build URL. Must be HTTP or HTTPS.
`environment`	no	Environment label.
`targetAgent`	no	Target agent name.
`attackPackId`	no	Attack-pack ID.
`attackPackScenario`	no	Attack-pack scenario name.
`run.report`	yes	Report object.
`run.transcript`	full transcript mode only	Transcript object.
`run.scenarioYaml`	full transcript mode only	Raw scenario YAML.
`run.metadata`	full transcript mode only	Run metadata.

run.report must include:

startedAt and endedAt must be valid dates. endedAt must be after or equal to startedAt.

If status is passed, failures must be empty.

If status is failed or warning, failures must include at least one finding.

Duplicate failures are rejected.

When mode is sanitized_findings, the payload must not include:

When mode is full_transcript_opt_in, run.transcript is required and must match the report run ID and scenario name.

The CLI verifies full transcript policy before reading or sending full evidence.

Use:

roleplay doctor --cloud --project <project-id> --api-key <key>