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. Keys are environment-specific:

Environment	Purpose
`live`	Production — decisions are enforced
`shadow`	Shadow mode — decisions are logged, not enforced
`test`	Testing — no audit trail, no rate limits

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
Authorization: Bearer your_api_key

{
  "intent": {
    "agent": {
      "id": "customer_service_bot_v2"
    },
    "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:

Type	Description
`communicate`	Sending information to a person or system
`transact`	Moving money, assets, or value
`access`	Reading or retrieving sensitive information
`control`	Operating a physical or digital system
`publish`	Making content publicly visible
`recommend`	Advising a human on a decision
`modify`	Changing a record, configuration, or state

The Governance Decision

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

Verdict	What it means
approve	Action may proceed as declared
approve_modified	Action may proceed with modifications — use the returned payload, not the original
escalate	Action requires human review before proceeding
block	Action is denied, with reasoning and suggested alternatives

Note: A block returns HTTP 200, not 403. A block is a successful governance decision, not an error. HTTP 4xx codes are reserved for actual request failures.

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

Endpoints

POST /v1/intents

Submit an intent for synchronous governance evaluation

POST /v1/intents/async

Submit an intent for asynchronous evaluation with webhook or polling

GET /v1/intents/{intent_id}/decision

Retrieve the governance decision for a previously submitted intent

GET /v1/intents/{intent_id}/audit

Retrieve the full governance audit trail

GET /v1/intents

List and filter intent declarations

POST /v1/agents

SDKs

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