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 live block verdict, your organization's contact receives an email with the blocking policy, risk score, regulatory citations and suggested alternatives — at most one per agent per hour; later blocks in that hour are counted in the next email. The email has three buttons:

• Approve This Action — the agent may carry out this action once: its next retry of the same action within 24 hours is approved
• Deny & Note — confirms the block was correct and logs your note
• Open the GaaS dashboard — ask about the intent there

An approval covers the same action only: same agent, action type, verb, target and target sensitivity, with no larger amount, audience or set of data categories, and blocked by no policy the original was not. It is used once. The retry still runs every policy; its decision is approve with a human_override object saying who approved it and when, and its audit record carries the same, inside the record's hash. A retry that would be escalated is not changed: it still goes to a person for review.

To act on an approval, your agent retries the same action with the blocked intent's ID in context_provided.prior_intents. GET /v1/intents/{intent_id}/override reports not_approved, approved, used or expired, so an agent can wait for an approval before retrying. A decision.overridden webhook fires when a person approves. The approval link is signed and needs no sign-in, so anyone holding the email can use it.

Approving in the dashboard. An operator or admin whose sign-in passed two-factor can approve any of the organization's blocked actions at https://the.gaas.is/approvals/{intent_id} — including blocks that were not emailed because of the one-per-hour limit. The approval records who approved. An admin can turn on Settings → Organization → Approve blocked actions only in the dashboard, with two-factor sign-in: the email's Approve button then opens that page instead of approving.

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, GaaS writes a plain-English explanation of the decision — a narrative summary, risk factors, the policies that decided it, and a recommended next step. Explanations cover live-mode block, escalate and approve_modified decisions, and approve decisions with a risk score of 0.5 or more; shadow and test decisions are not explained. They are written by Claude (claude-opus-5-5), with a template-based fallback that never fails.

Explanations arrive shortly after the verdict, not with it. The decision is returned as soon as it is made — your agent never waits for the explanation — so decision.explanation in the POST /v1/intents response is null. Fetch it from GET /v1/intents/{intent_id}/explanation:

• 200 — the explanation is ready (it is also stored on the decision, so GET /v1/intents/{intent_id}/decision carries it from then on).
• 202 — still being written. Wait the number of seconds in the Retry-After header and ask again; stop at poll_until.
• 404 — no explanation will be produced. error.details[0].reason says why: disabled, not_live, not_eligible or unavailable.

Enable via the environment variable GAAS_FEATURE_EXPLAIN_DECISIONS=true.

// GET /v1/intents/{intent_id}/explanation → 202 while it is being written
{
  "status": "pending",
  "intent_id": "int_abc123",
  "retry_after_seconds": 5,
  "poll_until": "2026-09-28T17:04:12Z",
  "message": "The explanation is generated after the verdict is returned and is not ready yet. ..."
}

// → 200 once it is ready
{
  "explanation": {
    "decision_id": "dec_abc123",
    "narrative": "This action was blocked because the agent tried to email payment card data to a customer. Card data may only leave the organisation over an approved, encrypted channel.",
    "risk_factors": ["Regulated payment card data", "External recipient"],
    "policy_citations": ["pol_t1_001: PII Transmission Security"],
    "recommendation": "Remove the card data or send it through an approved encrypted channel, then resubmit.",
    "generated_at": "2026-09-28T17:00:31Z",
    "model": "claude-opus-5-5"
  }
}

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.