API by area

Approvals, policies and the kill switch

39 endpoints. Paths are relative to https://api.sandscale.dev; values in braces are ones you fill in.

API reference · Authentication · Errors

MethodPathWhat it does
GET/api/v1/approval-channelsList approval channels
POST/api/v1/approval-channelsCreate an approval channel
DELETE/api/v1/approval-channels/{id}Delete one approval channel
POST/api/v1/approvalsCreate an approval
GET/api/v1/approvals/{id}One request, to a caller the inbox would show it to; any other request is not found.
POST/api/v1/approvals/{id}/dispatchDispatch an approval
POST/api/v1/approvals/{id}/issue-token(also POST /api/v1/approvals/{id}/token)
POST/api/v1/approvals/{id}/token(also POST /api/v1/approvals/{id}/token)
POST/api/v1/approvals/{id}/voteVote an approval
GET/api/v1/approvals/inboxList inbox
GET/api/v1/approvals/inbox/{id}Get one inbox
POST/api/v1/approvals/inbox/{id}/decisionDecision an inbox
GET/api/v1/approvals/metricsList metrics
GET/api/v1/approvals/pendingThe open requests the caller may see, filtered as the inbox filters them, never every request of the organization to any member.
GET/api/v1/approvals/pollList poll
GET/api/v1/approvals/recurringOrg_id defaults to the caller's organization.
POST/api/v1/approvals/recurringCreate a recurring
POST/api/v1/approvals/redeemCreate a redeem
GET/api/v1/approvals/settingsList settings
GET/api/v1/approvals/slaList sla
PUT/api/v1/approvals/slaSet sla
POST/api/v1/approvals/sla/process(admin)
POST/api/v1/approvals/verify-tokenCreate a verify token
GET/api/v1/dlp/builtin-patternsList builtin patterns
GET/api/v1/dlp/context-rulesList context rules
POST/api/v1/dlp/context-rulesCreate a context rule
DELETE/api/v1/dlp/context-rules/{id}Delete one context rule
POST/api/v1/dlp/detokenizeCreate a detokenize
GET/api/v1/dlp/enforcementList enforcement
GET/api/v1/dlp/patternsList patterns
POST/api/v1/dlp/patternsCreate a pattern
DELETE/api/v1/dlp/patterns/{id}Delete one pattern
POST/api/v1/dlp/scanCreate a scan
GET/api/v1/dlp/statsList stats
POST/api/v1/dlp/tokenizeCreate a tokenize
GET/api/v1/dlp/violationsThe caller's organization's violations, newest first. type keeps one pattern type and tool the violations whose tool_name equals it exactly (1 to 128 printable characters); both are applied before the limit.
POST/api/v1/dlp/violations/{id}/false-positiveFalse positive a violation
GET/api/v1/orgs/{orgID}/governance/killswitchList killswitch
PUT/api/v1/orgs/{orgID}/governance/killswitchTurns the organization's workspace kill switch on or off (governance:manage). The change and its audit entry commit together.

Endpoints

GET /api/v1/approval-channels

List approval channels

Permission
api:access
Query parameters
org_id

POST /api/v1/approval-channels

Create an approval channel

Permission
approvals:admin
Request body
object

DELETE /api/v1/approval-channels/{id}

Delete one approval channel

Permission
approvals:admin
Path parameters
id

POST /api/v1/approvals

Create an approval

Permission
api:access
Request body
ApprovalRequest
Response
201: ApprovalRequest
Errors
400: project_mismatch; 403: not_project_member; 404: project_not_found; 409: project_inactive; 503: projects_unavailable

GET /api/v1/approvals/{id}

One request, to a caller the inbox would show it to; any other request is not found.

Permission
api:access
Path parameters
id
Response
200: ApprovalRequest
Errors
400: no_organization; 401: unauthorized

POST /api/v1/approvals/{id}/dispatch

Dispatch an approval

Permission
api:access
Path parameters
id
Response
200: object of string

POST /api/v1/approvals/{id}/issue-token

(also POST /api/v1/approvals/{id}/token)

Permission
api:access
Path parameters
id
Request body
object
Response
201: object of string
Errors
403: person_required

POST /api/v1/approvals/{id}/token

(also POST /api/v1/approvals/{id}/token)

Permission
api:access
Path parameters
id
Request body
object
Response
201: object of string
Errors
403: person_required

POST /api/v1/approvals/{id}/vote

Vote an approval

Permission
api:access
Path parameters
id
Request body
object
Response
200: object of string
Errors
403: person_required

GET /api/v1/approvals/inbox

List inbox

Permission
api:access
Query parameters
cursor, limit, relation, source, view
Response
200: InboxPage
Errors
400: no_organization, reason_required, scope_required, validation_error; 401: unauthorized; 403: not_an_approver, self_approval; 404: not_found; 409: already_decided, already_voted, content_changed, expired, out_of_turn; 422: too_many_items; 428: reviewed_hash_required; 503: source_unavailable

GET /api/v1/approvals/inbox/{id}

Get one inbox

Permission
api:access
Path parameters
id
Response
200: InboxDetail
Errors
400: no_organization, reason_required, scope_required, validation_error; 401: unauthorized; 403: not_an_approver, self_approval; 404: not_found; 409: already_decided, already_voted, content_changed, expired, out_of_turn; 422: too_many_items; 428: reviewed_hash_required; 503: source_unavailable

POST /api/v1/approvals/inbox/{id}/decision

Decision an inbox

Permission
api:access
Path parameters
id
Request body
object
Response
200: InboxDetail
Errors
400: invalid_json, no_organization, reason_required, scope_required, validation_error; 401: unauthorized; 403: not_an_approver, person_required, self_approval, user_required; 404: not_found; 409: already_decided, already_voted, content_changed, expired, out_of_turn; 422: too_many_items; 428: reviewed_hash_required; 503: source_unavailable

GET /api/v1/approvals/metrics

List metrics

Permission
approvals:read
Query parameters
from, org_id, to
Response
200: ApprovalMetrics

GET /api/v1/approvals/pending

The open requests the caller may see, filtered as the inbox filters them, never every request of the organization to any member.

Permission
api:access
Query parameters
project_id
Response
200: ApprovalInfo
Errors
400: no_organization, project_mismatch; 401: unauthorized; 403: not_project_member; 404: project_not_found; 409: project_inactive; 503: projects_unavailable

GET /api/v1/approvals/poll

List poll

Permission
api:access
Query parameters
action_hash
Response
200: object of string; 202: ApprovalRequest

GET /api/v1/approvals/recurring

Org_id defaults to the caller's organization.

Permission
api:access
Query parameters
action_hash, org_id, user_id
Response
200: object of boolean

POST /api/v1/approvals/recurring

Create a recurring

Permission
api:access
Request body
object
Response
201: object of string
Errors
403: person_required

POST /api/v1/approvals/redeem

Create a redeem

Permission
none
Query parameters
token
Request body
object
Response
200: object of string

GET /api/v1/approvals/settings

List settings

Permission
approvals:read
Response
200: Settings
Errors
400: no_organization, reason_required, scope_required, validation_error; 401: unauthorized; 403: not_an_approver, self_approval; 404: not_found; 409: already_decided, already_voted, content_changed, expired, out_of_turn; 422: too_many_items; 428: reviewed_hash_required; 503: source_unavailable

GET /api/v1/approvals/sla

List sla

Permission
api:access
Query parameters
org_id
Response
200: ApprovalSLA

PUT /api/v1/approvals/sla

Set sla

Permission
approvals:admin
Request body
object
Response
200: object of string

POST /api/v1/approvals/sla/process

(admin)

Permission
approvals:admin
Response
200: object of integer

POST /api/v1/approvals/verify-token

Create a verify token

Permission
api:access
Request body
object
Response
object of string; 200: object of string

GET /api/v1/dlp/builtin-patterns

List builtin patterns

Permission
dlp:read
Response
200: object of any
Errors
401: unauthorized; 403: forbidden

GET /api/v1/dlp/context-rules

List context rules

Permission
dlp:read
Response
200: object of any
Errors
401: unauthorized; 503: service_unavailable

POST /api/v1/dlp/context-rules

Create a context rule

Permission
dlp:manage
Request body
ContextRule
Response
201: ContextRule
Errors
400: invalid_json, validation_error; 401: unauthorized; 403: person_required; 404: not_found; 415: content_type; 503: audit_unavailable, service_unavailable

DELETE /api/v1/dlp/context-rules/{id}

Delete one context rule

Permission
dlp:manage
Path parameters
id
Response
200: object of any
Errors
400: validation_error; 401: unauthorized; 403: person_required; 404: not_found; 503: audit_unavailable, service_unavailable

POST /api/v1/dlp/detokenize

Create a detokenize

Permission
dlp:detokenize
Request body
object
Response
200: object of any
Errors
400: invalid_json, validation_error; 401: unauthorized; 415: content_type; 503: audit_unavailable, service_unavailable

GET /api/v1/dlp/enforcement

List enforcement

Permission
dlp:read
Response
200: object of any
Errors
401: unauthorized; 403: forbidden

GET /api/v1/dlp/patterns

List patterns

Permission
dlp:read
Response
200: object of any
Errors
401: unauthorized

POST /api/v1/dlp/patterns

Create a pattern

Permission
dlp:manage
Request body
object
Response
201: object of any
Errors
400: invalid_json, pattern, validation_error; 401: unauthorized; 404: not_found; 415: content_type; 503: audit_unavailable

DELETE /api/v1/dlp/patterns/{id}

Delete one pattern

Permission
dlp:manage
Path parameters
id
Response
200: object of any
Errors
400: validation_error; 401: unauthorized; 403: person_required; 404: not_found; 500: pattern; 503: audit_unavailable

POST /api/v1/dlp/scan

Create a scan

Permission
api:access
Request body
object
Response
200: ExtendedScanResult
Errors
400: invalid_json, validation_error; 401: unauthorized; 415: content_type; 503: service_unavailable

GET /api/v1/dlp/stats

List stats

Permission
dlp:read
Response
200: object of any
Errors
401: unauthorized

POST /api/v1/dlp/tokenize

Create a tokenize

Permission
api:access
Request body
object
Response
200: object of any
Errors
400: invalid_json, validation_error; 401: unauthorized; 415: content_type; 503: dlp_token_key_unavailable, service_unavailable

GET /api/v1/dlp/violations

The caller's organization's violations, newest first. type keeps one pattern type and tool the violations whose tool_name equals it exactly (1 to 128 printable characters); both are applied before the limit.

Permission
dlp:read
Query parameters
tool, type
Response
200: object of any
Errors
400: invalid_query; 401: unauthorized

POST /api/v1/dlp/violations/{id}/false-positive

False positive a violation

Permission
dlp:manage
Path parameters
id
Response
200: object of any
Errors
400: validation_error; 401: unauthorized; 403: own_violation, person_required; 404: not_found; 500: violation; 503: audit_unavailable

GET /api/v1/orgs/{orgID}/governance/killswitch

List killswitch

Permission
api:access
Path parameters
orgID
Response
200: KillSwitch
Errors
400: invalid_org_id; 503: governance_store_unavailable

PUT /api/v1/orgs/{orgID}/governance/killswitch

Turns the organization's workspace kill switch on or off (governance:manage). The change and its audit entry commit together.

Permission
governance:manage
Path parameters
orgID
Request body
govSetKillSwitchRequest
Response
200: object of any
Errors
400: confirmation_mismatch, invalid_json, invalid_org_id; 403: person_required, step_up_failed, step_up_required; 415: content_type; 500: kill_switch_partial; 503: audit_unavailable, governance_store_unavailable, unavailable

Objects

object

FieldTypeDescription
org_idstring
channel_typestring
configJSON

object

FieldTypeDescription
decisionstring
reasonstring
scopestring
reviewed_hashstring

object

FieldTypeDescription
org_idstring
user_idstring
action_hashstring
approval_idstring
duration_hoursinteger

object

FieldTypeDescription
tokenstring
decisionstring
commentstring

object

FieldTypeDescription
tokenstring

object

FieldTypeDescription
ttl_minutesinteger

object

FieldTypeDescription
ttl_minutesinteger

object

FieldTypeDescription
decisionstring
commentstring

object

FieldTypeDescription
tokenstring

object

FieldTypeDescription
namestring
pattern_typestring
patternstring
actionstring

object

FieldTypeDescription
textstring
agent_rolestring
destinationstring

object

FieldTypeDescription
valuestring

object

FieldTypeDescription
org_idstring
slaApprovalSLA

ApprovalInfo

The payload sent via notification channels.

FieldTypeDescription
idstring
agent_idstring
session_idstring
actionstring
resourcestring
paramsJSON
expires_attimestamp
created_attimestamp
project_id optionalstring

ApprovalMetrics

ApprovalMetrics holds aggregate statistics for a time window.

FieldTypeDescription
org_idstring
fromtimestamp
totimestamp
total_approvedinteger
total_rejectedinteger
total_pendinginteger
sla_violationsinteger
avg_decision_time_secsnumber
auto_approvedinteger

ApprovalRequest

The full data model for an approval request.

FieldTypeDescription
idstring
nrn optionalstringThe request's NRN; the API handler sets it, and a client's value is never stored.
org_idstring
subject_type optionalstring
subject_id optionalstring
agent_idstring
session_idstring
user_id optionalstring
actionstring
resourcestring
paramsJSON
reason optionalstring
statusstring
approval_typestring
approver_group optionalstring
quorum_requiredinteger
quorum_totalinteger
action_hash optionalstring
sla_warn_minsinteger
sla_escalate_minsinteger
sla_reject_minsinteger
sla_escalation_group optionalstring
conditions optionalJSON
approvers optionalarray of stringThe ordered approver sequence of a sequential request: user IDs, each of whom must approve in turn. Required for TypeSequential, ignored otherwise.
valid_for_minsintegerValidForMins bounds how long an approved request stays valid after its decision; 0 means it does not lapse.
escalated_at optionaltimestamp
escalation_countinteger
decided_by optionalstring
decided_at optionaltimestamp
expires_attimestamp
created_attimestamp
project_id optionalstringThe Directory project the request gates; "" for an account-level request. The database refuses a project of another organization.
requester_api_key_id optionalstringThe API key that filed the request through the public API, set by Sandscale from the authenticated principal (never from the body). The key's owner is the requester, so nobody approves what they asked for through their own key, and only that key or that person reads the request's outcome by action hash.

ApprovalSLA

The persisted, org-level SLA configuration. It maps to approval_sla_configs and is applied to new requests unless overridden per-request.

FieldTypeDescription
warn_after_minsinteger
escalate_after_minsinteger
auto_reject_after_minsinteger
escalation_target_groupstring

ChannelField

One setting of a channel type.

FieldTypeDescription
namestring
labelstring
hint optionalstring
secretboolean
requiredboolean

ChannelSummary

An approval channel without its secrets, with its last delivery.

FieldTypeDescription
idstring
typestring
type_labelstring
destinationstring
enabledboolean
created_attimestamp
last_status optionalstring
last_error optionalstring
last_sent_at optionaltimestamp

ChannelType

A kind of approval channel and its settings.

FieldTypeDescription
typestring
labelstring
fieldsarray of ChannelField

GrantScope

A choice a source offers with an approval.

FieldTypeDescription
valuestring
labelstring

InboxDetail

A request with its votes, notifications and parameters.

FieldTypeDescription
idstring
nrn optionalstringThe request's NRN; the API handler sets it.
sourcestring
source_labelstring
titlestring
actionstring
resourcestring
agent_id optionalstring
requester_id optionalstring
requester_email optionalstring
project_id optionalstring
statusstring
status_labelstring
openbooleanTrue while the request waits for a decision (pending or escalated).
approval_typestring
type_labelstring
approvalsinteger
approvals_neededinteger
approver_group optionalstring
created_attimestamp
expires_at optionaltimestampWhen an open request expires; zero (left out) for a source whose requests do not expire.
decided_by optionalstring
decided_by_email optionalstring
decided_at optionaltimestamp
decision_reason optionalstring
sla optionalInboxSLAThe request's SLA state; nil for a source without SLA thresholds.
can_decidebooleanWhether the viewer's vote would be accepted now; CannotDecide says why not when it would not.
cannot_decide optionalstring
decide_on optionalstringDecideOn says where the viewer decides when CanDecide is set: DecideOnInbox (this inbox's decision route), DecideOnGrantPage (a vault grant, approved with a passkey on its own page) or DecideOnFilePage (an agent instruction file version, approved on the review page after reading it). Empty when the viewer cannot decide.
is_requesterbooleanSet by the server when the viewer filed the request.
grant_scopes optionalarray of GrantScopeThe choices an approval of this request takes (an agent permission is granted once or for the session); empty when it takes none.
reason optionalstring
paramsJSON
votesarray of InboxVote
dispatchesarray of InboxDispatch
review_hash optionalstringReviewHash names exactly what an approval of this request approves, for a source whose approval binds to reviewed content (an agent file version's content SHA-256); the approver sends it back as InboxDecision.ReviewedHash. Empty for every other source.

InboxDispatch

One notification sent for a request.

FieldTypeDescription
channel_typestring
channel_labelstring
statusstring
error optionalstring
dispatched_attimestamp

InboxItem

One approval request as the inbox shows it to a viewer.

FieldTypeDescription
idstring
nrn optionalstringThe request's NRN; the API handler sets it.
sourcestring
source_labelstring
titlestring
actionstring
resourcestring
agent_id optionalstring
requester_id optionalstring
requester_email optionalstring
project_id optionalstring
statusstring
status_labelstring
openbooleanTrue while the request waits for a decision (pending or escalated).
approval_typestring
type_labelstring
approvalsinteger
approvals_neededinteger
approver_group optionalstring
created_attimestamp
expires_at optionaltimestampWhen an open request expires; zero (left out) for a source whose requests do not expire.
decided_by optionalstring
decided_by_email optionalstring
decided_at optionaltimestamp
decision_reason optionalstring
sla optionalInboxSLAThe request's SLA state; nil for a source without SLA thresholds.
can_decidebooleanWhether the viewer's vote would be accepted now; CannotDecide says why not when it would not.
cannot_decide optionalstring
decide_on optionalstringDecideOn says where the viewer decides when CanDecide is set: DecideOnInbox (this inbox's decision route), DecideOnGrantPage (a vault grant, approved with a passkey on its own page) or DecideOnFilePage (an agent instruction file version, approved on the review page after reading it). Empty when the viewer cannot decide.
is_requesterbooleanSet by the server when the viewer filed the request.
grant_scopes optionalarray of GrantScopeThe choices an approval of this request takes (an agent permission is granted once or for the session); empty when it takes none.

InboxPage

A page of the inbox.

FieldTypeDescription
viewstring
source optionalstringThe source filter of the page, "" for every source.
sourcesarray of InboxSourceInfoWhat the inbox can be filtered by.
scopestring"organization" when the page lists every request of the organization, or "mine" when it lists only those visible to the viewer (no approvals:read). A "mine" page may hold fewer items than the limit and still carry a next_cursor.
itemsarray of InboxItem
next_cursor optionalstring
summaryInboxSummary
relation optionalstringThe relation filter of the page, "" for none.

InboxSLA

A request's SLA state: its thresholds as times and where it stands.

FieldTypeDescription
statestring
labelstring
warn_attimestamp
escalate_attimestamp
reject_attimestamp
next_label optionalstring
next_at optionaltimestamp

InboxSourceInfo

InboxSourceInfo names a source the inbox can be filtered by.

FieldTypeDescription
keystring
labelstring

InboxSummary

InboxSummary counts the organization's open requests by SLA state.

FieldTypeDescription
openinteger
warninginteger
escalation_dueinteger
escalatedinteger
overdueinteger
to_decide_on_pageinteger
matchingintegerMatching counts every request of the relation the page belongs to, whatever the page limit (open and decided); 0 for a page without a relation. For such a page Open and the SLA counts are those of the relation's open requests.

InboxVote

One vote on a request.

FieldTypeDescription
approver_idstring
approver_email optionalstring
decisionstring
decision_labelstring
comment optionalstring
voted_attimestamp

SLASettings

The organization's SLA as the settings show it.

FieldTypeDescription
warn_after_minsinteger
escalate_after_minsinteger
auto_reject_after_minsinteger
escalation_target_groupstring
configuredbooleanFalse when the organization uses DefaultSLA.
max_minutesinteger

Settings

The organization's approval configuration: its SLA and its channels.

FieldTypeDescription
slaSLASettings
channelsarray of ChannelSummary
channel_typesarray of ChannelType

ContextRule

ContextRule defines a policy: for a given (agent_role, data_class, destination) triple, enforce the specified action. Wildcards ("*") are supported in all three dimensions.

FieldTypeDescription
idstring
nrn optionalstringThe rule's NRN; the API handler sets it.
org_idstring
agent_rolestring
data_classstring
destinationstring
actionstringBlock | redact | tokenize | alert | allow
reasonstring
priorityintegerLower number = higher priority
created_attimestamp

ExtendedScanResult

The output of ScanText; richer than the base ScanResult.

FieldTypeDescription
HasViolationbooleanTrue when at least one pattern matched.
Violationsarray of ViolationViolations lists every individual match.
RedactedTextstringThe input text with every match replaced by [REDACTED:<type>]. With no match it is the input text.
classification optionalstringThe strictest classification among Violations; empty when nothing matched. No finding does not make text public, so callers keep their own classification in that case.
org_idstring
agent_rolestring
destinationstring
context_action optionalstringThe action dictated by the matching context rule (if any). When empty, no context rule matched and pattern-level actions apply.
context_reason optionalstring
tokenization_failed optionalbooleanSet when a span due for tokenization could not be stored in the vault and was redacted instead.

Violation

Violation describes a single match found during a scan.

FieldTypeDescription
PatternNamestring
PatternTypestring
MatchStartinteger
MatchEndinteger
ActionstringBlock | warn | redact | log_only
classification optionalstringThe context classification level of the matched data.

KillSwitch

KillSwitch represents the state of the kill switch for an org.

FieldTypeDescription
org_iduuid
activeboolean
reason optionalstring
updated_attimestamp
org_kill_switch_engagedbooleanThe organization kill switch (the AI SOC or endpoint switch), which stops and refuses workspaces too; OrgKillSwitchSources names what engaged it.
org_kill_switch_sources optionalarray of string
engagedbooleanThe server's answer: the organization's workspaces are refused and stopped.

govSetKillSwitchRequest

FieldTypeDescription
activeboolean
reason optionalstring
confirm_account_name optionalstring
mfa_code optionalstring

This page is generated from the server's route table and the Go handlers that serve each route. Do not edit it by hand.