What Data Is Sent to the Governance API¶

This document describes exactly what your integration transmits to agentgovernance.dev, what is stored, and what is discarded — for every API endpoint. It is written for developers reviewing the governance API before integrating it into a production system.

The short version¶

Anonymous evaluate — you send text, the API analyzes it in-memory, only result metadata is stored (not the text), deleted after 30 days.
Authenticated observe — you send text, the API analyzes it, up to 500 characters of matched text is stored only when a pattern is detected. Unmatched text is discarded.
Govern gates — you send gate names and metadata you provide. No agent output text is involved.
IP addresses — hashed before storage. Raw IPs never written to the database.
API keys — hashed immediately. Plaintext never stored. Lost keys cannot be recovered.

Endpoint-by-endpoint breakdown¶

`POST /api/v1/evaluate` — Anonymous pattern detection¶

What you send:

{
  "text": "your agent output here",
  "mode": "text",
  "framework": "langgraph"
}

Field	Required	Description
`text`	Yes	The agent output to evaluate
`mode`	No	`"text"` or `"trace"`. Defaults to `"text"`
`framework`	No	Framework hint for trace parsing. Has no effect on text mode

What is stored:

Field	Stored	Notes
`text`	No	Analyzed in-memory. Discarded after analysis.
IP address	As hash	SHA-256 hash of request IP. Raw IP not stored.
Input character count	Yes	`text.length`. Used for usage analytics only.
Input mode	Yes	`"text"` or `"trace"`
Input framework	Yes	Detected or provided framework label
Evaluation result	Yes	Full result JSON: patterns detected, confidence, severity, matched text snippets within the result. Retained 30 days.
Patterns detected count	Yes	Integer.
Highest severity	Yes	P1 / P2 / P3 / ADV / null

Retention: 30 days. Records have an expiresAt timestamp set at creation. Expired records are deleted.

Authentication: Not required. Rate limited to 10 evaluations/day per IP hash.

`POST /api/v1/evaluate` — Authenticated pattern detection¶

Same as anonymous, with these additions:

What you send: Same request body, plus Authorization: Bearer <key> header.

Additional storage:

Field	Stored	Notes
API key ID	Yes	UUID reference to your key record (not the key itself)
Daily limit	Enforced	Default 100/day per key

Everything else is identical to anonymous evaluate. Your text is still not stored.

`POST /api/v1/observe/assess` — Behavioral observation (requires auth)¶

This endpoint is designed for continuous monitoring of a governed agent. It is different from evaluate in one important way: it persists observations to your organization's audit record.

What you send:

{
  "text": "your agent output here",
  "agentId": "uuid",
  "runId": "uuid"
}

Field	Required	Description
`text`	Yes	The agent output to analyze
`agentId`	No	UUID of the registered agent that produced this output
`runId`	No	UUID of the active governance run

What is stored — per detected pattern:

Field	Stored	Notes
`orgId`	Yes	Your organization ID. Used for data isolation.
`agentId`	Yes	If provided. Null if omitted.
`runId`	Yes	If provided. Null if omitted.
Pattern ID	Yes	e.g., `BP-001`
Confidence	Yes	0.0 – 1.0
Severity	Yes	P1 / P2 / P3 / ADV
Detection method	Yes	`regex`, `semantic`, or `context-aware`
Evidence — matches	Yes	The specific regex match strings that triggered detection
Evidence — text excerpt	Yes	`text.slice(0, 500)` — first 500 characters of your submitted text

What is not stored:

Text beyond the first 500 characters
Any text from calls where no pattern is detected (the full text is discarded)
The full untruncated text, even for positive detections

Audit trail: When patterns are detected, an audit trail entry is created containing: org ID, entity type (observation), observation ID, action (patterns_detected), actor (api), and the list of detected pattern IDs. The text content is not duplicated in the audit trail.

Retention: Behavioral observations are retained for the duration of your organization subscription. They are not auto-deleted on a time schedule (unlike evaluations).

`POST /api/v1/govern/gate` — Gate submission (requires auth)¶

Gate endpoints record the progression of your agent through governance phases (PLAN → BUILD → REVIEW_ENG → REMEDIATE → REVIEW_ARCH → APPROVE).

What you send:

{
  "runId": "uuid",
  "gate": "build",
  "action": "submitted",
  "actor": "ci-system",
  "evidence": { "commitRef": "abc123", "testsPassed": true }
}

Field	Required	Description
`runId`	Yes	UUID of the governance run
`gate`	Yes	Which gate: `plan`, `build`, `review_eng`, `remediate`, `review_arch`, `approve`
`action`	Yes	`submitted`, `approved`, or `rejected`
`actor`	Yes	String identifier for who or what submitted the gate
`evidence`	No	Any JSON object. Stored as-is. Not validated or processed.

What is stored:

Field	Stored	Notes
`runId`	Yes	References the governance run
`gate`	Yes	Gate name
`action`	Yes	Action type
`actor`	Yes	As provided
`evidence`	Yes	Full JSON object as provided. You control what goes here.
Timestamp	Yes	Server-side UTC timestamp

No agent output text is transmitted to or stored by gate endpoints. The evidence field is metadata you provide — typically commit references, CI results, or reviewer identifiers.

`POST /api/v1/agents/register` — Agent registration (requires auth)¶

What you send:

{
  "name": "my-research-agent",
  "framework": "langgraph"
}

What is stored: Agent name, framework, status (registered), org ID, creation timestamp, and any config object you provide. No behavioral content involved.

`POST /api/v1/govern/runs` — Governance run start (requires auth)¶

What you send:

{
  "agentId": "uuid",
  "metadata": { "version": "1.2.3" }
}

What is stored: Agent ID, org ID, initial status, initial gate (plan), metadata you provide, start timestamp. No behavioral content involved.

What is never stored¶

Data	Notes
Full agent output text	Analyzed in-memory, discarded. Only 500-char excerpt stored for positive detections via observe/assess.
Raw IP addresses	Hashed before any write operation.
API keys in plaintext	Hashed immediately. Returned once at registration, then the plaintext is gone.
Cross-organization data	All authenticated data is partitioned by `orgId`. One org cannot access another's data.
Training data	Agent output is never used to train, fine-tune, or benchmark models.

Data flow diagram¶

Your agent output (text)
        │
        ▼
  Governance API
  ┌─────────────────────────────────────┐
  │  1. Receive text                    │
  │  2. Run pattern detection (memory)  │
  │  3. Discard text (or 500-char       │
  │     excerpt if pattern detected     │
  │     and using observe/assess)       │
  │  4. Write result metadata to DB     │
  └─────────────────────────────────────┘
        │
        ▼
  Neon PostgreSQL (US region)
  - Result metadata
  - Pattern IDs + confidence
  - Org/agent/run identifiers
  - 500-char excerpt (observe only, detected only)

Hashing details¶

IP address hashing:

IPs are hashed using SHA-256 before any database write. The hash is one-way and cannot be reversed to recover an IP address. It is used only to enforce daily rate limits and for aggregate analytics (e.g., unique daily visitors).

API key hashing:

API keys for the evaluate endpoint are hashed using bcrypt. Keys for the organization API (observe, govern) are hashed using SHA-256. In both cases: the plaintext key is generated, returned in the registration response, and then the plaintext is discarded. Only the hash is stored.

Retention schedule¶

Data type	Auto-deleted?	After
Evaluation records	Yes	30 days
Rate limit buckets	Yes	End of UTC day
Behavioral observations	No	Subscription duration
Governance runs	No	Subscription duration
Gate events	No	Subscription duration
Audit trail	No	Subscription duration
Agent registrations	No	Until manually deleted
Email / org records	No	Until deletion requested

To request deletion of your organization and all associated data, open an issue at github.com/agentgovernance/governance-engine.

Infrastructure¶

Component	Provider	Notes
Database	Neon — serverless PostgreSQL	US region
API server	Replit	Deployed from governance-engine repo
Docs site	Replit	Static MkDocs build

Questions¶

Questions about data handling not covered here can be raised as an issue at github.com/agentgovernance/governance-engine. For data processing agreement requirements, use the contact form.

What Data Is Sent to the Governance API¶

The short version¶

Endpoint-by-endpoint breakdown¶

POST /api/v1/evaluate — Anonymous pattern detection¶

POST /api/v1/evaluate — Authenticated pattern detection¶

POST /api/v1/observe/assess — Behavioral observation (requires auth)¶

POST /api/v1/govern/gate — Gate submission (requires auth)¶

POST /api/v1/agents/register — Agent registration (requires auth)¶

POST /api/v1/govern/runs — Governance run start (requires auth)¶

What is never stored¶

Data flow diagram¶

Hashing details¶

Retention schedule¶

Infrastructure¶

Questions¶

`POST /api/v1/evaluate` — Anonymous pattern detection¶

`POST /api/v1/evaluate` — Authenticated pattern detection¶

`POST /api/v1/observe/assess` — Behavioral observation (requires auth)¶

`POST /api/v1/govern/gate` — Gate submission (requires auth)¶

`POST /api/v1/agents/register` — Agent registration (requires auth)¶

`POST /api/v1/govern/runs` — Governance run start (requires auth)¶