Explain an execution: plan, policy decisions, grant, receipt

GET

/v1/graph/explain/{executionId}

const url = 'https://api.trustysweep.com/v1/graph/explain/example';
const options = {method: 'GET', headers: {cookie: 'sweep_session=<sweep_session>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url https://api.trustysweep.com/v1/graph/explain/example \
  --cookie sweep_session=<sweep_session>

Authorizations

sessionCookie
sessionToken
apiKey
inventory:read
oauth2
inventory:read

Parameters

Path Parameters

executionId

required

string

/^exe_[0-9A-HJKMNP-TV-Z]{26}$/

Responses

200

application/json

object

execution_id

required

Prefixed ULID (exe_…)

string

/^exe_[0-9A-HJKMNP-TV-Z]{26}$/

plan

One of:

object
null

A Shadow Sweep plan: a low-cost logical preflight built from metadata, hashes and provider revision markers. Never mutates provider state.

object

planId

required

Prefixed ULID (pln_…)

string

/^pln_[0-9A-HJKMNP-TV-Z]{26}$/

planVersion

required

string

Allowed values: 1

tenantId

required

string

userId

required

string

actor

required

object

type

required

string

Allowed values: user sweep_automation developer_application external_agent service connector

principalId

required

string

delegatingUserId

One of:

string
null

string

applicationId

One of:

string
null

string

agentId

One of:

string
null

string

grantId

One of:

string
null

string

intent

required

string

Allowed values: sweep rescue restore migrate export unsubscribe simulation

operationClasses

required

Array<string>

Allowed values: discover preserve write remove restore migrate monitor automate billable_execute

simulated

required

boolean

createdAt

required

string format: date-time

expiresAt

required

string format: date-time

sourceMarkers

required

Array<object>

object

provider

required

string

Allowed values: google_gmail google_drive microsoft_outlook microsoft_onedrive dropbox apple_local s3_compatible trusty_vault simulated

sourceId

required

string

kind

required

string

Allowed values: history_id delta_token page_token cursor etag snapshot_hash none

value

required

string

observedAt

required

string format: date-time

objects

required

Array<object>

object

assetId

required

Prefixed ULID (ast_…)

string

/^ast_[0-9A-HJKMNP-TV-Z]{26}$/

sourceId

required

Prefixed ULID (src_…)

string

/^src_[0-9A-HJKMNP-TV-Z]{26}$/

provider

required

string

Allowed values: google_gmail google_drive microsoft_outlook microsoft_onedrive dropbox apple_local s3_compatible trusty_vault simulated

providerObjectId

required

string

expectedVersion

One of:

string
null

string

expectedSizeBytes

required

integer

expectedSha256

One of:

string
null

string

storageClass

string

Allowed values: preserve likely_removable review promotional duplicate large_attachment cold recent protected_by_rule

actions

required

Array<string>

>= 1 items

Allowed values: preserve trash restore copy move unsubscribe noop

preservationElected

required

boolean

excluded

Array<object>

object

assetId

required

Prefixed ULID (ast_…)

string

/^ast_[0-9A-HJKMNP-TV-Z]{26}$/

reason

required

string

Allowed values: low_confidence policy_exclusion protected_by_rule unsupported_capability over_grant_limit recent shared

detail

string

destination

One of:

object
null

object

destinationId

required

string

provider

required

string

Allowed values: google_gmail google_drive microsoft_outlook microsoft_onedrive dropbox apple_local s3_compatible trusty_vault simulated

label

required

string

external

boolean

pathTemplate

One of:

string
null

string

metadataMapping

object

key

additional properties

string

permissionMapping

string

Allowed values: preserve_where_supported drop owner_only

knownLossiness

Array<string>

preservationRequired

required

boolean

projection

required

object

objectCount

required

integer

bytesToPreserve

required

integer

bytesToRemove

required

integer

bytesToTransfer

required

integer

projectedReclaimBytes

required

integer

projectedQuota

required

Array<object>

object

sourceId

required

string

usedBytesAfter

required

integer

limitBytes

One of:

integer
null

integer

percentAfter

One of:

number
null

number

policy

One of:

object
null

object

policyVersion

required

string

decision

required

string

Allowed values: allow deny step_up_required

reasons

required

Array<string>

requiredApprovals

Array<string>

Allowed values: human_user developer_owner ceiling_increase scope_step_up

decisionId

string

meter

One of:

object
null

object

rateCardVersion

required

string

currency

required

string

Allowed values: usd

lines

required

Array<object>

object

meter

required

string

quantity

required

number

unit

required

string

estimatedCents

required

integer

includedInAllowance

required

boolean

estimatedCents

required

integer

includedAllowanceApplied

required

boolean

withinStandingEnvelope

One of:

boolean
null

boolean

state

required

string

Allowed values: draft validated authorized committing committed executed partially_executed stale expired rejected cancelled

hash

Deterministic SHA-256 over material fields; any material change produces a new hash and requires fresh authorization.

string

authorization

One of:

object
null

object

authorizedAt

required

string format: date-time

authorizedBy

required

string

actionDecisionId

required

string

commercialAuthorizationId

One of:

string
null

string

planHashAtAuthorization

required

string

policy_decisions

required

Array<object>

object

decisionId

required

string

policyVersion

required

string

decision

required

string

Allowed values: allow deny step_up_required

reasons

required

Array<string>

matchedGrantId

One of:

string
null

string

riskClass

required

string

Allowed values: read low medium high critical

obligations

Array<string>

evaluatedAt

required

string format: date-time

grant

One of:

object
null

Versioned user delegation grant constraining what a principal may do on behalf of a user.

object

required

Prefixed ULID (grt_…)

string

/^grt_[0-9A-HJKMNP-TV-Z]{26}$/

version

required

integer

userId

required

string

tenantId

required

string

principalId

required

string

status

required

string

Allowed values: active revoked expired

createdAt

required

string format: date-time

expiresAt

One of:

string
null

string format: date-time

revokedAt

One of:

string
null

string format: date-time

operations

required

Array<string>

Allowed values: discover preserve write remove restore migrate monitor automate billable_execute

actions

required

Array<string>

Allowed values: read_inventory read_quota read_vault search_vault create_plan preserve trash restore copy move migrate_external unsubscribe monitor automate manage_grants delete_vault_object delete_account permanent_delete

sources

One of:

Array<string>
null

Array<string>

containers

One of:

Array<string>
null

Array<string>

assetKinds

One of:

Array<string>
null

Array<string>

maxObjectsPerPlan

One of:

integer
null

integer

maxBytesPerPlan

One of:

integer
null

integer

maxPlansPerDay

One of:

integer
null

integer

allowedDestinations

One of:

Array<string>
null

Array<string>

allowExternalDestinations

boolean

allowDestructive

boolean

allowAutomatic

boolean

requireShadowPlan

boolean

requireHumanApprovalAbove

string

Allowed values: read low medium high critical

minConfidence

number

commercialCeilingCents

One of:

integer
null

integer

timeWindow

One of:

object
null

object

startHourUtc

required

integer

endHourUtc

required

integer

receipt

One of:

object
null

Durable, tamper-evident execution receipt signed with the platform Ed25519 key published at /.well-known/sweep-receipts.json.

object

receiptVersion

required

string

Allowed values: 1

receiptId

required

Prefixed ULID (rcp_…)

string

/^rcp_[0-9A-HJKMNP-TV-Z]{26}$/

executionId

required

Prefixed ULID (exe_…)

string

/^exe_[0-9A-HJKMNP-TV-Z]{26}$/

planId

required

Prefixed ULID (pln_…)

string

/^pln_[0-9A-HJKMNP-TV-Z]{26}$/

planHash

required

string

tenantRef

required

string

actor

required

object

type

required

string

Allowed values: user sweep_automation developer_application external_agent service connector

principalId

required

string

delegatingUserId

One of:

string
null

string

applicationId

One of:

string
null

string

agentId

One of:

string
null

string

grantId

One of:

string
null

string

delegatingUserId

One of:

string
null

string

authorization

required

object

actionDecisionId

required

string

grantId

One of:

string
null

string

commercialAuthorizationId

One of:

string
null

string

policyVersion

required

string

rateCardVersion

One of:

string
null

string

intent

required

string

simulated

required

boolean

attempted

required

integer

completed

required

integer

failed

required

integer

objects

required

Array<object>

object

assetId

required

string

providerObjectId

required

string

actions

required

Array<string>

status

required

string

Allowed values: completed partial failed skipped

vaultObjectId

One of:

string
null

string

vaultSha256

One of:

string
null

string

providerResultId

One of:

string
null

string

bytes

integer

error

One of:

string
null

string

restorable

boolean

before

required

Array<object>

object

sourceId

required

string

provider

required

string

Allowed values: google_gmail google_drive microsoft_outlook microsoft_onedrive dropbox apple_local s3_compatible trusty_vault simulated

usedBytes

One of:

integer
null

integer

limitBytes

One of:

integer
null

integer

observedAt

required

string format: date-time

after

required

Array<object>

object

sourceId

required

string

provider

required

string

Allowed values: google_gmail google_drive microsoft_outlook microsoft_onedrive dropbox apple_local s3_compatible trusty_vault simulated

usedBytes

One of:

integer
null

integer

limitBytes

One of:

integer
null

integer

observedAt

required

string format: date-time

bytesPreserved

required

integer

bytesRemoved

required

integer

bytesTransferred

required

integer

measuredReclaimBytes

One of:

integer
null

integer

charges

required

Array<object>

object

meter

required

string

quantity

required

number

unit

required

string

cents

required

integer

usageEventId

required

string

startedAt

required

string format: date-time

finishedAt

required

string format: date-time

restoration

required

object

capable

required

boolean

until

One of:

string
null

string format: date-time

method

One of:

string
null

string

errors

Array<string>

hash

Sha256 of canonical JSON of the receipt without hash/signature

string

signature

object

alg

required

string

Allowed values: Ed25519

kid

required

string

sig

required

Base64url Ed25519 signature over hash

string

edges

required

Array<object>

object

from

required

string

required

string

type

required

string

required

string format: date-time

executionId

One of:

string
null

string

props

object

key

additional properties

Example

{
  "execution_id": "exe_01J8Z3K9M2Q4R6S8T0V2W4X6Y8",
  "plan": {
    "planId": "pln_01J8Z3K9M2Q4R6S8T0V2W4X6Y8",
    "planVersion": "1",
    "actor": {
      "type": "user"
    },
    "intent": "sweep",
    "operationClasses": [
      "discover"
    ],
    "sourceMarkers": [
      {
        "provider": "google_gmail",
        "kind": "history_id"
      }
    ],
    "objects": [
      {
        "assetId": "ast_01J8Z3K9M2Q4R6S8T0V2W4X6Y8",
        "sourceId": "src_01J8Z3K9M2Q4R6S8T0V2W4X6Y8",
        "provider": "google_gmail",
        "storageClass": "preserve",
        "actions": [
          "preserve"
        ]
      }
    ],
    "excluded": [
      {
        "assetId": "ast_01J8Z3K9M2Q4R6S8T0V2W4X6Y8",
        "reason": "low_confidence"
      }
    ],
    "destination": {
      "provider": "google_gmail",
      "permissionMapping": "preserve_where_supported"
    },
    "policy": {
      "decision": "allow",
      "requiredApprovals": [
        "human_user"
      ]
    },
    "meter": {
      "currency": "usd"
    },
    "state": "draft"
  },
  "policy_decisions": [
    {
      "decision": "allow",
      "riskClass": "read"
    }
  ],
  "grant": {
    "id": "grt_01J8Z3K9M2Q4R6S8T0V2W4X6Y8",
    "status": "active",
    "operations": [
      "discover"
    ],
    "actions": [
      "read_inventory"
    ],
    "requireHumanApprovalAbove": "read"
  },
  "receipt": {
    "receiptVersion": "1",
    "receiptId": "rcp_01J8Z3K9M2Q4R6S8T0V2W4X6Y8",
    "executionId": "exe_01J8Z3K9M2Q4R6S8T0V2W4X6Y8",
    "planId": "pln_01J8Z3K9M2Q4R6S8T0V2W4X6Y8",
    "actor": {
      "type": "user"
    },
    "objects": [
      {
        "status": "completed"
      }
    ],
    "before": [
      {
        "provider": "google_gmail"
      }
    ],
    "after": [
      {
        "provider": "google_gmail"
      }
    ],
    "signature": {
      "alg": "Ed25519"
    }
  }
}

Headers

RateLimit-Limit

integer

Requests allowed in the current window.

RateLimit-Remaining

integer

Requests remaining in the current window.

RateLimit-Reset

integer

Seconds until the window resets.

400

Validation failed

application/problem+json

RFC 9457 problem details.

object

type

required

Https://developers.trustysweep.com/errors/

string format: uri

titlerequired

string

statusrequired

integer

detail

string

coderequired

Machine-readable error code from errors.json

string

request_idrequired

string

errors

Array<object>

object

pathrequired

string

messagerequired

string

`Example^generated`

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "code": "example",
  "request_id": "example",
  "errors": [
    {
      "path": "example",
      "message": "example"
    }
  ]
}

`401`

Section titled “401”

Unauthenticated

Media typeapplication/problem+json
RFC 9457 problem details.
object
typerequired
Https://developers.trustysweep.com/errors/

string format: uri
titlerequired
string
statusrequired
integer
detail
string
coderequired
Machine-readable error code from errors.json

string
request_idrequired
string
errors
Array<object>
object
pathrequired
string
messagerequired
string
Example^generated
{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "code": "example",
  "request_id": "example",
  "errors": [
    {
      "path": "example",
      "message": "example"
    }
  ]
}

`403`

Section titled “403”

Forbidden / action denied / step-up required

Media typeapplication/problem+json
RFC 9457 problem details.
object
typerequired
Https://developers.trustysweep.com/errors/

string format: uri
titlerequired
string
statusrequired
integer
detail
string
coderequired
Machine-readable error code from errors.json

string
request_idrequired
string
errors
Array<object>
object
pathrequired
string
messagerequired
string
Example^generated
{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "code": "example",
  "request_id": "example",
  "errors": [
    {
      "path": "example",
      "message": "example"
    }
  ]
}

`404`

Section titled “404”

Not found

Media typeapplication/problem+json
RFC 9457 problem details.
object
typerequired
Https://developers.trustysweep.com/errors/

string format: uri
titlerequired
string
statusrequired
integer
detail
string
coderequired
Machine-readable error code from errors.json

string
request_idrequired
string
errors
Array<object>
object
pathrequired
string
messagerequired
string
Example^generated
{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "code": "example",
  "request_id": "example",
  "errors": [
    {
      "path": "example",
      "message": "example"
    }
  ]
}

`429`

Section titled “429”

Rate limited

Media typeapplication/problem+json
RFC 9457 problem details.
object
typerequired
Https://developers.trustysweep.com/errors/

string format: uri
titlerequired
string
statusrequired
integer
detail
string
coderequired
Machine-readable error code from errors.json

string
request_idrequired
string
errors
Array<object>
object
pathrequired
string
messagerequired
string
Example^generated
{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "code": "example",
  "request_id": "example",
  "errors": [
    {
      "path": "example",
      "message": "example"
    }
  ]
}

`Headers`

Section titled “Headers”

Retry-After

integer

Seconds to wait before retrying.

RateLimit-Limit

integer

Requests allowed in the current window.

RateLimit-Remaining

integer

Requests remaining in the current window.

RateLimit-Reset

integer

Seconds until the window resets.

`500`

Section titled “500”

Internal error

Media typeapplication/problem+json
RFC 9457 problem details.
object
typerequired
Https://developers.trustysweep.com/errors/

string format: uri
titlerequired
string
statusrequired
integer
detail
string
coderequired
Machine-readable error code from errors.json

string
request_idrequired
string
errors
Array<object>
object
pathrequired
string
messagerequired
string
Example^generated
{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "code": "example",
  "request_id": "example",
  "errors": [
    {
      "path": "example",
      "message": "example"
    }
  ]
}

Explain an execution: plan, policy decisions, grant, receipt

Authorizations

Parameters

Path Parameters

Responses

200

Example

Headers

400

Examplegenerated

401

Examplegenerated

403

Examplegenerated

404

Examplegenerated

429

Examplegenerated

Headers

500

Examplegenerated

`Example^generated`

`401`

`Example^generated`

`403`

`Example^generated`

`404`

`Example^generated`

`429`

`Example^generated`

`Headers`

`500`

`Example^generated`