Guardrail API

Table of Contents

• upsquad/guardrail/v1/guardrail.proto

  • CreateGuardrailRequest

  • CreateGuardrailResponse

  • DeleteGuardrailRequest

  • DeleteGuardrailResponse

  • GetGuardrailRequest

  • GetGuardrailResponse

  • GetUsageStatsRequest

  • GetUsageStatsResponse

  • Guardrail

  • GuardrailTemplate

  • ListGuardrailsRequest

  • ListGuardrailsResponse

  • ListTemplatesRequest

  • ListTemplatesResponse

  • ListTokenValuesRequest

  • ListTokenValuesResponse

  • SampleDiff

  • SentenceItem

  • SimulateAgainstHistoryRequest

  • SimulateAgainstHistoryResponse

  • TokenValue

  • TokenValueOption

  • UpdateGuardrailRequest

  • UpdateGuardrailResponse

  • Severity

  • TokenKind

  • GuardrailService

• Scalar Value Types

Top

upsquad/guardrail/v1/guardrail.proto

CreateGuardrailRequest

CreateGuardrailRequest seeds a new Guardrail. Sentence may be empty during draft; server rejects on save when the rule is unparseable.

Field	Type	Label	Description
name	string		name is the founder-supplied label.
sentence	SentenceItem	repeated	sentence is the rule body.
scope	string		scope is a free-text scope label.
severity	Severity		severity drives the severity pill.
enabled	bool		enabled controls whether the guardrail is live on save.

CreateGuardrailResponse

CreateGuardrailResponse echoes the persisted Guardrail with id assigned.

Field	Type	Label	Description
guardrail	Guardrail		guardrail is the stored row including the assigned GR-NN id.

DeleteGuardrailRequest

DeleteGuardrailRequest marks a row deleted (soft).

Field	Type	Label	Description
id	string		id is the GR-NN target.

DeleteGuardrailResponse

DeleteGuardrailResponse is empty on success.

GetGuardrailRequest

GetGuardrailRequest targets a single guardrail by id.

Field	Type	Label	Description
id	string		id is the GR-NN form.

GetGuardrailResponse

GetGuardrailResponse returns the guardrail or a NotFound error.

Field	Type	Label	Description
guardrail	Guardrail		guardrail is the stored row.

GetUsageStatsRequest

GetUsageStatsRequest queries usage of one guardrail.

Field	Type	Label	Description
id	string		id selects the persisted guardrail.
window_days	int32		window_days caps at 30. Defaults to 7.

GetUsageStatsResponse

GetUsageStatsResponse is the aggregate stats card.

Field	Type	Label	Description
triggered	int32		triggered is the total event count that this guardrail evaluated.
blocked	int32		blocked is the count of events the guardrail blocked.
allowed	int32		allowed is the count of events the guardrail allowed.
last_fired_at	google.protobuf.Timestamp		last_fired_at is unset when the guardrail has never fired.

Guardrail

Guardrail is the overlay resource. Joins to existing policy rows are resolved server-side; the wire shape is sentence-first, not policy-first.

Field	Type	Label	Description
id	string		id is the human-readable GR-NN form (e.g. "GR-04"). Sequential per tenant. Re-used across drafts of the same rule (Update keeps the id).
name	string		name is the founder-supplied label (e.g. "Refund ceiling").
sentence	SentenceItem	repeated	sentence is the ordered list of items (text + tokens) that renders the rule. The prototype consumes this as an alternating array.
scope	string		scope is a free-text scope label (e.g. "All teams", "Finance"). The prototype renders it verbatim; v1 stores it as text and a future LLD will resolve it to org_unit ids when compiling to policies.
severity	Severity		severity drives the severity pill rendered on the row + detail view.
enabled	bool		enabled gates whether the guardrail is live. Disabled rows are returned by List so the UI can show them with reduced opacity.
last_edit	string		last_edit is a human label (e.g. "Marcus R · Apr 23"). Composed server-side from updated_by + updated_at.
created_at	google.protobuf.Timestamp		created_at is the wall-clock insert time.
updated_at	google.protobuf.Timestamp		updated_at is the wall-clock time of the last mutation.

GuardrailTemplate

GuardrailTemplate seeds step-1 of the New Guardrail modal.

Field	Type	Label	Description
id	string		id is the template id (e.g. "ceiling", "data-export").
label	string		label is the displayed template name.
description	string		description is the one-line subtitle on the template card.
icon	string		icon is a short glyph string ("$", "⊟", "↗", "⌥", "◴", "+"). The UI looks it up against an icon set; passing it on the wire keeps the frontend free of duplicate hard-coded mappings.
prefill_sentence	SentenceItem	repeated	prefill_sentence seeds the editable sentence on step 2.
prefill_scope	string		prefill_scope seeds the scope dropdown.
prefill_severity	Severity		prefill_severity seeds the severity selector.

ListGuardrailsRequest

ListGuardrailsRequest is paginated. The Guardrails redesign loads up to a few-dozen rows in practice; pagination is defence in depth.

Field	Type	Label	Description
page_size	int32		page_size caps returned rows. Default 50, max 200.
page_token	string		page_token is an opaque cursor returned by a prior call.

ListGuardrailsResponse

ListGuardrailsResponse returns one page of guardrails.

Field	Type	Label	Description
guardrails	Guardrail	repeated	guardrails is the returned page.
next_page_token	string		next_page_token is empty when no more rows exist.

ListTemplatesRequest

ListTemplatesRequest takes no parameters. Templates are static.

ListTemplatesResponse

ListTemplatesResponse returns the 6 hardcoded templates.

Field	Type	Label	Description
templates	GuardrailTemplate	repeated	templates is the ordered list.

ListTokenValuesRequest

ListTokenValuesRequest is keyed on TokenKind. v1 ignores tenant context and returns static values; future LLDs may resolve dynamic values (e.g. role names from RBAC, dataclasses from compliance registry).

Field	Type	Label	Description
kind	TokenKind		kind selects the dropdown to populate.

ListTokenValuesResponse

ListTokenValuesResponse returns the populated dropdown.

Field	Type	Label	Description
values	TokenValueOption	repeated	values is empty when the kind is free-input (number / text) — the UI then renders a numeric or text input instead of a dropdown.

SampleDiff

SampleDiff is one audit row whose verdict would have flipped.

Field	Type	Label	Description
event_id	string		event_id is the audit log primary key.
event_at	google.protobuf.Timestamp		event_at is the audit row's created_at.
current_verdict	string		current_verdict is one of "allow", "deny", "requires_approval", or "n/a" when the engine could not produce a verdict.
would_be_verdict	string		would_be_verdict is the verdict the simulated guardrail would yield.
summary	string		summary is a human-readable one-line description of the event for the UI's "Show diff" panel.

SentenceItem

SentenceItem is one element of a Guardrail.sentence. Exactly one of text or token is set. Mirrors the JSX tokens.map(t => typeof t === "string" ? <span/> : <Token/>).

Field	Type	Label	Description
text	string		text is a literal string fragment ("Block any refund over").
token	TokenValue		token is a typed value slot (e.g. money / clearance).

SimulateAgainstHistoryRequest

SimulateAgainstHistoryRequest replays audit events. Either pass an existing guardrail id and let the server use its persisted sentence, or override with edited_sentence to preview an unsaved edit.

Field	Type	Label	Description
id	string		id selects the persisted guardrail. Required.
edited_sentence	SentenceItem	repeated	edited_sentence overrides the persisted sentence for preview. May be empty (= use persisted).
window_days	int32		window_days is capped at 30. Defaults to 7 when 0.

SimulateAgainstHistoryResponse

SimulateAgainstHistoryResponse is the simulation outcome.

Field	Type	Label	Description
would_change	int32		would_change is the count of events whose verdict differs.
kept	int32		kept is the count of events whose verdict is unchanged.
sample_diffs	SampleDiff	repeated	sample_diffs holds up to 20 example rows for the UI drawer.
total_events_evaluated	int32		total_events_evaluated equals would_change + kept (audit window size). Returned for the prototype's "X of Y events" copy.

TokenValue

TokenValue is one colored slot inside a guardrail sentence. The prototype stores tokens as { kind, value } objects intermixed with raw strings; SentenceItem mirrors that shape.

Field	Type	Label	Description
kind	TokenKind		kind is the discriminator (TOKEN_KIND_*).
value	string		value is the rendered form (e.g. "2500" for a money token, "Standard" for a clearance token, "8pm" for a time token). The UI formats based on kind ($ prefix, locale grouping for numbers).

TokenValueOption

TokenValueOption is one selectable option for a select-typed token.

Field	Type	Label	Description
value	string		value is the wire form stored on the sentence token.
label	string		label is the display form rendered in the dropdown. Often equal to value but kept distinct for future i18n.

UpdateGuardrailRequest

UpdateGuardrailRequest replaces all editable fields on the row.

Field	Type	Label	Description
id	string		id is the GR-NN target.
name	string		name is the new label.
sentence	SentenceItem	repeated	sentence is the new rule body.
scope	string		scope is the new scope label.
severity	Severity		severity is the new severity band.
enabled	bool		enabled is the new enable bit.

UpdateGuardrailResponse

UpdateGuardrailResponse echoes the updated Guardrail.

Field	Type	Label	Description
guardrail	Guardrail		guardrail is the stored row after update.

Severity

Severity mirrors the prototype's three-band severity selector.

Name	Number	Description
SEVERITY_UNSPECIFIED	0	SEVERITY_UNSPECIFIED is the proto3 zero value; rejected at the edge.
SEVERITY_LOW	1	SEVERITY_LOW maps to the "low" pill colour.
SEVERITY_MED	2	SEVERITY_MED maps to the "med" pill colour (warn band).
SEVERITY_HIGH	3	SEVERITY_HIGH maps to the "high" pill colour (danger band).

TokenKind

TokenKind enumerates the 11 supported token kinds. Mirrors the React prototype's kind discriminator on sentence tokens.

Name	Number	Description
TOKEN_KIND_UNSPECIFIED	0	TOKEN_KIND_UNSPECIFIED is the proto3 zero value; rejected at the edge.
TOKEN_KIND_MONEY	1	TOKEN_KIND_MONEY renders as a currency-formatted dollar amount.
TOKEN_KIND_COUNT	2	TOKEN_KIND_COUNT renders as a locale-grouped integer count.
TOKEN_KIND_CLEARANCE	3	TOKEN_KIND_CLEARANCE selects from the 5-tier clearance ladder.
TOKEN_KIND_ROLE	4	TOKEN_KIND_ROLE selects from RBAC role names.
TOKEN_KIND_CHANNEL	5	TOKEN_KIND_CHANNEL selects from outbound communication channels.
TOKEN_KIND_DATACLASS	6	TOKEN_KIND_DATACLASS selects from the data classification registry.
TOKEN_KIND_SCOPE	7	TOKEN_KIND_SCOPE selects from agent / team scope phrases.
TOKEN_KIND_AUTONOMY	8	TOKEN_KIND_AUTONOMY selects from autonomy levels (Supervised etc.).
TOKEN_KIND_TIME	9	TOKEN_KIND_TIME stores a free-text time-of-day phrase ("8pm").
TOKEN_KIND_TOOL	10	TOKEN_KIND_TOOL stores a free-text tool identifier ("GitHub · merge").
TOKEN_KIND_BRANCH	11	TOKEN_KIND_BRANCH selects a source-control branch name.

GuardrailService

GuardrailService exposes the founder-facing guardrail authoring surface.

Method Name	Request Type	Response Type	Description
CreateGuardrail	CreateGuardrailRequest	CreateGuardrailResponse	CreateGuardrail persists a new Guardrail and returns it with the assigned GR-NN id. Sentence tokens are validated against TokenKind.
GetGuardrail	GetGuardrailRequest	GetGuardrailResponse	GetGuardrail returns a single Guardrail by id (e.g. "GR-12").
UpdateGuardrail	UpdateGuardrailRequest	UpdateGuardrailResponse	UpdateGuardrail mutates a stored Guardrail. The sentence may be edited in-place; simulation cache invalidates when the sentence_hash changes.
DeleteGuardrail	DeleteGuardrailRequest	DeleteGuardrailResponse	DeleteGuardrail soft-deletes a Guardrail. Listing skips deleted rows.
ListGuardrails	ListGuardrailsRequest	ListGuardrailsResponse	ListGuardrails returns all Guardrails in the caller's tenant. Paginated.
ListTokenValues	ListTokenValuesRequest	ListTokenValuesResponse	ListTokenValues returns the candidate values for a token kind. The result powers the dropdowns on the inline-edit UI (guardrails-new.jsx TOKEN_OPTS). v1 returns static values for select-typed kinds and an empty list (= caller free-text input) for number / text kinds.
SimulateAgainstHistory	SimulateAgainstHistoryRequest	SimulateAgainstHistoryResponse	SimulateAgainstHistory replays recent audit events through the policy engine using the (optionally edited) guardrail sentence and reports how many events would have changed outcome.
GetUsageStats	GetUsageStatsRequest	GetUsageStatsResponse	GetUsageStats aggregates triggered / blocked / allowed counts from the audit log for a guardrail over a window (capped at 30 days).
ListTemplates	ListTemplatesRequest	ListTemplatesResponse	ListTemplates returns the 6 hardcoded New-Guardrail templates that seed step 1 of the New Guardrail modal (guardrails-new.jsx TEMPLATES).

Scalar Value Types

.proto Type	Notes	C++	Java	Python	Go	C#	PHP	Ruby
double		double	double	float	float64	double	float	Float
float		float	float	float	float32	float	float	Float
int32	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
int64	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.	int64	long	int/long	int64	long	integer/string	Bignum
uint32	Uses variable-length encoding.	uint32	int	int/long	uint32	uint	integer	Bignum or Fixnum (as required)
uint64	Uses variable-length encoding.	uint64	long	int/long	uint64	ulong	integer/string	Bignum or Fixnum (as required)
sint32	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sint64	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.	int64	long	int/long	int64	long	integer/string	Bignum
fixed32	Always four bytes. More efficient than uint32 if values are often greater than 2^28.	uint32	int	int	uint32	uint	integer	Bignum or Fixnum (as required)
fixed64	Always eight bytes. More efficient than uint64 if values are often greater than 2^56.	uint64	long	int/long	uint64	ulong	integer/string	Bignum
sfixed32	Always four bytes.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sfixed64	Always eight bytes.	int64	long	int/long	int64	long	integer/string	Bignum
bool		bool	boolean	boolean	bool	bool	boolean	TrueClass/FalseClass
string	A string must always contain UTF-8 encoded or 7-bit ASCII text.	string	String	str/unicode	string	string	string	String (UTF-8)
bytes	May contain any arbitrary sequence of bytes.	string	ByteString	str	[]byte	ByteString	string	String (ASCII-8BIT)