Intent Declaration API

The front door to GaaS governance. Every AI agent action begins with an intent declaration.

Core Concept

Before an AI agent takes any action, it declares what it intends to do, to whom, and with what impact. GaaS evaluates that declaration through a multi-stage governance pipeline and returns a decision: approve, modify, escalate, or block.

If an agent can't declare it, it can't do it. Opacity of intent is the primary risk vector in autonomous AI systems — GaaS eliminates it at the point of entry.

Authentication

Every request requires an API key scoped to your organization, passed via the X-API-Key header. Each key is bound to an org_id — all data returned is automatically scoped to that organization.

Shadow vs. live mode is controlled per-request via the ?mode=shadow query parameter, or by the membrane's lifecycle state. Both modes produce full audit trails. See Shadow Mode for details.

Submitting an Intent

An intent declaration includes the agent's identity, the action it wants to take, the target, the expected impact, and any context the agent already has. The schema adapts — lightweight for routine actions, verbose for high-stakes ones.

POST /v1/intents
Content-Type: application/json
X-API-Key: your_api_key

{
  "intent": {
    "agent": {
      "id": "customer_service_bot_v2",
      "framework": "custom"
    },
    "action": {
      "type": "COMMUNICATE",
      "verb": "send_email",
      "target": {
        "type": "PERSON",
        "identifier": "customer@example.com",
        "sensitivity": "CONFIDENTIAL"
      }
    },
    "payload": {
      "summary": "Send loan rate quote with APR disclosure",
      "content": {
        "recipient": "customer@example.com",
        "channel": "email",
        "message_body": "..."
      }
    },
    "estimated_impact": {
      "reversible": true,
      "financial_exposure_usd": 0,
      "audience_size": 1,
      "regulatory_domains": ["TILA"]
    }
  }
}

Action Types

GaaS recognizes seven categories of agent action, each with different governance implications:

The Governance Decision

Every intent submission returns a governance decision with one of four verdicts:

Block Notifications & Appeals

When GaaS issues a block verdict, the org admin automatically receives an email notification containing the blocking policy, risk score, regulatory citations, and suggested alternatives. The email includes three click-to-action buttons:

• Approve Override — records a human-approved exception in the audit trail
• Deny & Note — confirms the block was correct and logs the admin's note
• View in Dashboard — opens the decision detail page

Approving an override does not re-run the pipeline. The agent must resubmit the intent to receive a new governance decision. All appeal actions are recorded in the tamper-evident audit trail.

Agent Retry Tracking

When an agent resubmits a previously blocked intent, include the original intent ID in context_provided.prior_intents. GaaS detects the retry, attaches a retry_context object to the decision (with attempt count and prior verdict), and records a reformulation observation for the learning engine. Repeated retries of the same blocked action type surface as actionable insights in the governance dashboard.

Decisions include a risk assessment, the list of pipeline stages that executed, and a reference to the full audit record.

Governance Explainability

When enabled, every governance decision includes a plain-English explanation field containing a narrative summary, risk factors, and policy citations. Explanations are generated by an LLM (claude-haiku-4-5-20251001) with an automatic template-based fallback that never fails.

Enable via the environment variable GAAS_FEATURE_EXPLAIN_DECISIONS=true.

// GovernanceDecision.explanation (when enabled)
{
  "explanation": {
    "narrative": "This action was blocked because the agent attempted to access protected health information without a valid HIPAA authorization. Policy pol_t2_hipaa_001 requires explicit patient consent for PHI access.",
    "risk_factors": ["PHI access without authorization", "No consent record found"],
    "citations": ["pol_t2_hipaa_001", "45 CFR § 164.508"],
    "model": "claude-haiku-4-5-20251001"
  }
}

Session Trust Remaining

Every decision also includes a session_trust_remaining field (0.0–1.0) representing the agent's remaining trust budget. Trust starts at 1.0 and decays with risky decisions. When it reaches 0.10, policy pol_t1_015 blocks the agent. The field is null if session trust tracking is unavailable.

Endpoints

Idempotency

Include an Idempotency-Key header on intent submissions to prevent duplicate processing. If the same key is reused within 24 hours with the same content, the original decision is returned. Using the same key with different content returns a 409 conflict.

Bulk Submission

Submit up to 50 intents in a single API call using the batch endpoint. Intents are evaluated in parallel; partial failures don't abort the batch. See Advanced Features for full documentation.

A2A Gateway

AI agents can submit intents directly via the Agent-to-Agent (A2A) Protocol v0.3 JSON-RPC gateway. A2A requests are automatically translated into GaaS intent declarations, governed by the full pipeline, and translated back into A2A-compliant responses. This makes GaaS the governance control plane for multi-agent networks without requiring code changes in individual agents.

SDKs

Official SDKs for Python, TypeScript, and Java handle authentication, request construction, and response parsing. See the SDKs page or the Getting Started guide for usage examples.