API Reference

REST/HTTPS endpoints for cognitive offloading — governance evaluation, intent declaration, and shadow mode onboarding.

Base URL: https://api.gaas.is/v1
Protocol: HTTPS + JSON
Auth: Bearer token
OpenAPI Spec (YAML)

Authentication

All API requests (except onboarding) require an API key passed as a Bearer token in the Authorization header:

Authorization: Bearer gaas_live_org_...

You receive an API key when you create a shadow deployment via the onboarding endpoint. API keys are shown once at creation and cannot be retrieved later.

Shadow Mode

Shadow mode runs the full five-stage governance pipeline without enforcement. Actions are evaluated, deliberated, and audited — but never blocked. Use it to observe what governance reveals about your agents before activating enforcement.

To use shadow mode, append ?mode=shadow to any intent submission. The response includes "shadow": true to confirm.

Verdicts

Every governance decision produces one of four verdicts:

VerdictMeaningTypical Latency
APPROVEAction is safe to execute as declared< 100ms
MODIFYAction approved with modified parameters (returned in response)< 100ms
ESCALATEAction requires human review before execution200ms – 5s
BLOCKAction denied — policy violation or high risk< 100ms

Create Shadow Deployment

POST /v1/onboarding/quickstart

Register a new organization and receive API credentials for a 14-day free shadow deployment. No credit card required. No authentication needed for this endpoint.

Request Body
FieldTypeRequiredDescription
email string REQUIRED Contact email for the organization
org_name string REQUIRED Organization name
description string REQUIRED Description of what your AI agents do
Example Request
curl -X POST https://api.gaas.is/v1/onboarding/quickstart \
  -H "Content-Type: application/json" \
  -d '{
    "email": "engineer@acme.com",
    "org_name": "Acme Corp",
    "description": "Process customer refunds, generate compliance reports"
  }'
Example Response (201)
{
  "api_key": "gaas_live_org_a1b2c3d4e5f6",
  "membrane_id": "mem_acme_7x8y9z",
  "quickstart_snippet": "from gaas import GaaSClient\nclient = GaaSClient(api_key=\"gaas_live_org_a1b2c3d4e5f6\")",
  "next_steps": [
    "Submit intents with ?mode=shadow",
    "Review shadow stats in your dashboard",
    "Activate enforcement when ready"
  ]
}
Response Codes
201 Created 400 Invalid Request 409 Already Registered

Declare Intent

POST /v1/intents

Submit an agent's intended action through the full five-stage governance pipeline. The pipeline evaluates the intent, enriches context, applies policies, triggers deliberation if needed, and returns an audited decision.

Query Parameters
ParamTypeDefaultDescription
mode string live live = full enforcement (default). shadow = evaluate without blocking. test = deterministic integration testing.
Request Body
FieldTypeRequiredDescription
action string REQUIRED The action the agent intends to perform (e.g. send_email, execute_trade)
target string REQUIRED The target of the action (e.g. customer@example.com)
risk_level string OPTIONAL Agent's self-declared risk: low, medium, high, critical
context object OPTIONAL Additional context about the action (any key-value pairs)
agent_id string OPTIONAL Identifier for the agent submitting the intent
Example Request
curl -X POST "https://api.gaas.is/v1/intents?mode=shadow" \
  -H "Authorization: Bearer gaas_live_org_a1b2c3d4e5f6" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "send_email",
    "target": "customer@example.com",
    "risk_level": "low",
    "context": {
      "authenticated": true,
      "template": "welcome_series"
    },
    "agent_id": "cx-agent-7"
  }'
Example Response (200 — Approved)
{
  "approved": true,
  "verdict": "APPROVE",
  "modified_parameters": null,
  "pipeline": {
    "intent_declaration_ms": 3,
    "context_enrichment_ms": 41,
    "policy_evaluation_ms": 7,
    "deliberation_ms": null,
    "decision_audit_ms": 12,
    "total_ms": 63
  },
  "deliberation_triggered": false,
  "audit": {
    "hash": "a4f2...e819",
    "reason": "Action approved. Low risk, authenticated context, template-based."
  },
  "shadow": true
}
Example Response (200 — Blocked)
{
  "approved": false,
  "verdict": "BLOCK",
  "modified_parameters": null,
  "pipeline": {
    "intent_declaration_ms": 2,
    "context_enrichment_ms": 23,
    "policy_evaluation_ms": 6,
    "deliberation_ms": 180,
    "decision_audit_ms": 12,
    "total_ms": 223
  },
  "deliberation_triggered": true,
  "audit": {
    "hash": "7f3a...c291",
    "reason": "Stale sensor data. Contradiction between declared and live context."
  },
  "shadow": false
}
Response Codes
200 Decision Returned 401 Unauthorized 429 Rate Limited

SDK Integration

Use a GaaS SDK instead of calling the REST API directly:

Python

pip install gaas

from gaas import GaaSClient
client = GaaSClient(api_key="gaas_live_org_...")

decision = client.declare_intent(
    action="send_email",
    target="customer@example.com",
    risk_level="low",
    context={"authenticated": True, "template": "welcome_series"}
)

if decision.approved:
    send_email(decision.modified_parameters or original_params)

TypeScript

npm install @gaas/sdk

import { GaaSClient } from '@gaas/sdk';
const client = new GaaSClient({ apiKey: 'gaas_live_org_...' });

const decision = await client.declareIntent({
  action: 'send_email',
  target: 'customer@example.com',
  riskLevel: 'low',
  context: { authenticated: true, template: 'welcome_series' }
});

if (decision.approved) {
  sendEmail(decision.modifiedParameters ?? originalParams);
}

Java (Gradle)

implementation 'is.gaas:gaas-sdk:1.0.0'

GaaSClient client = new GaaSClient("gaas_live_org_...");

Decision decision = client.declareIntent(
    Intent.builder()
        .action("send_email")
        .target("customer@example.com")
        .riskLevel(RiskLevel.LOW)
        .context(Map.of("authenticated", true, "template", "welcome_series"))
        .build()
);

if (decision.isApproved()) {
    sendEmail(decision.getModifiedParameters().orElse(originalParams));
}
// FAQ

Frequently Asked Questions

Both modes return the same response structure: verdict, reasoning chain, risk score, and audit reference. In Shadow Mode the verdict shows what GaaS would have decided, but your application is expected to proceed regardless. Switch to enforcement by removing ?mode=shadow or switching from a gaas_shadow_ key prefix to a gaas_live_ prefix.

Registered agents: 50 req/s. Verified agents (30 days compliant history, full policy suite): 200 req/s. Certified agents (independent audit passed): 1,000 req/s. Contact support for burst capacity accommodation during defined testing windows.

Set governance_request.fallback_on_timeout in your intent declaration: block (default — fail-safe, recommended for production), allow_with_flag (proceed but flag for review), or escalate (hold for human decision). If no fallback is set, the default is block.

Yes. Use a gaas_test_ key prefix for test mode — runs the full pipeline against synthetic policy profiles without consuming production decisions or writing to your live audit trail. Responses are structurally identical to production.

Intent declaration body: 64KB max. Context field: 16KB max. Pre-process large payloads (e.g., raw document content) to summaries or hashes before declaring intent. SDK clients enforce these limits locally before making network requests.