Back to Documentation
Api ReferenceUpdated 2026-03-15

API Reference: Cognigate Endpoints

Complete REST API reference for the Cognigate governance enforcement engine -- /enforce, /intent, /proof/query, /proof/stats, and /admin/status.

Cognigate API Reference

The Cognigate governance enforcement engine exposes a REST API for intent parsing, policy enforcement, proof chain queries, and system administration. Base URL: https://cognigate.dev/v1

All endpoints require authentication via the Authorization header:

Authorization: Bearer <COGNIGATE_API_KEY>

POST /intent

Parse a natural-language or structured action request into a governance-evaluable intent.

Request

{
  "agentId": "agent-001",
  "input": "Read customer data from the sales database",
  "context": {
    "environment": "production",
    "requestSource": "api"
  }
}

| Field | Type | Required | Description | |---|---|---|---| | agentId | string | Yes | The CAR agent identifier | | input | string | Yes | Natural-language or structured action description | | context | object | No | Additional context for intent classification |

Response (200 OK)

{
  "intent": {
    "id": "int_abc123",
    "agentId": "agent-001",
    "parsedAction": "read_database",
    "riskLevel": "MEDIUM",
    "requiredCapabilities": ["read_database"],
    "context": {
      "environment": "production",
      "requestSource": "api",
      "dataClassification": "customer_pii"
    },
    "timestamp": "2026-03-15T10:30:00Z"
  },
  "confidence": 0.95,
  "alternatives": [
    {
      "parsedAction": "query_database",
      "confidence": 0.82
    }
  ]
}

Error Responses

| Status | Code | Description | |---|---|---| | 400 | INVALID_INPUT | Missing or malformed request body | | 401 | UNAUTHORIZED | Invalid or missing API key | | 404 | AGENT_NOT_FOUND | Agent ID does not exist | | 429 | RATE_LIMITED | Too many requests |

POST /enforce

Evaluate a parsed intent against governance policies and return an enforcement decision.

Request

{
  "intent": {
    "id": "int_abc123",
    "agentId": "agent-001",
    "parsedAction": "read_database",
    "riskLevel": "MEDIUM",
    "requiredCapabilities": ["read_database"],
    "context": {}
  }
}

| Field | Type | Required | Description | |---|---|---|---| | intent | Intent | Yes | A parsed intent object (from /intent or constructed manually) |

You can also combine intent parsing and enforcement in a single call by passing input directly:

{
  "agentId": "agent-001",
  "input": "Read customer data from the sales database"
}

Response (200 OK)

{
  "decision": "ALLOW",
  "reasoning": "Agent agent-001 (T4 Standard) has sufficient trust and capabilities for read_database (MEDIUM risk).",
  "grantedCapabilities": ["read_database"],
  "deniedCapabilities": [],
  "constraints": {
    "maxRecords": 10000,
    "timeoutMs": 30000
  },
  "proofId": "prf_xyz789",
  "trustSnapshot": {
    "score": 720,
    "tier": "T4",
    "tierName": "Standard"
  }
}

Decision Values

| Decision | Description | |---|---| | ALLOW | Action permitted. Proceed with grantedCapabilities. | | DENY | Action blocked. Check reasoning for explanation. | | ESCALATE | Action requires human approval. Route to designated reviewer. | | DEGRADE | Partial access. Some capabilities granted, others denied. |

Error Responses

| Status | Code | Description | |---|---|---| | 400 | INVALID_INTENT | Intent object is malformed or missing required fields | | 401 | UNAUTHORIZED | Invalid or missing API key | | 404 | AGENT_NOT_FOUND | Agent referenced in intent does not exist | | 422 | POLICY_ERROR | Governance policy evaluation failed |

GET /proof/query

Query the immutable proof chain for governance decision records.

Query Parameters

| Parameter | Type | Required | Description | |---|---|---|---| | entityId | string | Yes | Agent or entity ID to query proofs for | | from | ISO 8601 | No | Start of time range (inclusive) | | to | ISO 8601 | No | End of time range (inclusive) | | outcome | string | No | Filter by outcome: SUCCESS, FAILURE, ESCALATED | | decision | string | No | Filter by decision: ALLOW, DENY, ESCALATE, DEGRADE | | page | number | No | Page number (default: 1) | | pageSize | number | No | Records per page (default: 50, max: 200) |

Response (200 OK)

{
  "items": [
    {
      "id": "prf_xyz789",
      "entityId": "agent-001",
      "intentId": "int_abc123",
      "decision": "ALLOW",
      "reasoning": "Sufficient trust for read_database",
      "trustScore": 720,
      "trustTier": "T4",
      "riskLevel": "MEDIUM",
      "outcome": "SUCCESS",
      "timestamp": "2026-03-15T10:30:00Z",
      "hash": "sha256:a1b2c3d4e5f6...",
      "previousHash": "sha256:f6e5d4c3b2a1..."
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 50,
  "hasMore": false
}

Proof Record Fields

| Field | Description | |---|---| | id | Unique proof record identifier | | entityId | Agent that triggered the governance decision | | intentId | Reference to the parsed intent | | decision | Governance decision rendered | | reasoning | Human-readable explanation | | trustScore | Agent's trust score at decision time | | trustTier | Agent's trust tier at decision time | | riskLevel | Risk level of the requested action | | outcome | Post-execution outcome (if reported) | | timestamp | ISO 8601 timestamp of the decision | | hash | SHA-256 hash of this record | | previousHash | SHA-256 hash of the previous record in the chain |

GET /proof/stats

Get aggregate statistics for an entity's proof chain.

Query Parameters

| Parameter | Type | Required | Description | |---|---|---|---| | entityId | string | Yes | Agent or entity ID | | from | ISO 8601 | No | Start of time range | | to | ISO 8601 | No | End of time range |

Response (200 OK)

{
  "entityId": "agent-001",
  "totalRecords": 1247,
  "successRate": 0.94,
  "averageTrustScore": 715,
  "chainIntegrity": true,
  "decisionBreakdown": {
    "ALLOW": 1102,
    "DENY": 45,
    "ESCALATE": 78,
    "DEGRADE": 22
  },
  "riskBreakdown": {
    "LOW": 650,
    "MEDIUM": 420,
    "HIGH": 155,
    "CRITICAL": 22
  },
  "period": {
    "from": "2026-01-01T00:00:00Z",
    "to": "2026-03-15T23:59:59Z"
  }
}

GET /admin/status

Health check and system status endpoint for monitoring and observability.

Response (200 OK)

{
  "status": "healthy",
  "version": "1.4.2",
  "uptime": 864000,
  "components": {
    "gateway": "healthy",
    "trustEngine": "healthy",
    "proofChain": "healthy",
    "intentParser": "healthy",
    "database": "healthy"
  },
  "metrics": {
    "activeAgents": 156,
    "decisionsToday": 12450,
    "averageLatencyMs": 45,
    "proofChainLength": 2847291,
    "escalationsToday": 23
  },
  "timestamp": "2026-03-15T10:30:00Z"
}

Status Values

| Status | Description | |---|---| | healthy | All systems operational | | degraded | Some components experiencing issues; governance still functional | | unhealthy | Critical components down; governance may be unavailable |

TypeScript Client SDK

All endpoints are accessible via the @vorionsys/cognigate TypeScript SDK:

import { Cognigate } from '@vorionsys/cognigate';

const client = new Cognigate({
  apiKey: process.env.COGNIGATE_API_KEY!,
});

// POST /intent
const parsed = await client.governance.parseIntent(agentId, input);

// POST /enforce
const result = await client.governance.enforce(parsed.intent);

// Combined (POST /enforce with input)
const { intent, result: govResult } = await client.governance.evaluate(agentId, input);

// GET /proof/query
const proofs = await client.proofs.list(agentId, { from, pageSize: 50 });

// GET /proof/stats
const stats = await client.proofs.getStats(agentId);

// GET /admin/status (admin API key required)
// Available via direct HTTP request

Error Handling

import { CognigateError } from '@vorionsys/cognigate';

try {
  await client.governance.evaluate(agentId, input);
} catch (error) {
  if (error instanceof CognigateError) {
    console.log(error.code);     // 'NOT_FOUND', 'UNAUTHORIZED', etc.
    console.log(error.status);   // HTTP status code
    console.log(error.message);  // Human-readable message
    console.log(error.details);  // Additional context
  }
}

The client automatically retries server errors (5xx) with exponential backoff. Client errors (4xx) are thrown immediately.

Rate Limits

| Plan | Requests/minute | Burst | |---|---|---| | Free | 60 | 10 | | Pro | 600 | 100 | | Enterprise | Custom | Custom |

Rate-limited responses return 429 Too Many Requests with a Retry-After header.

Webhook Events

Cognigate can send webhook notifications for governance events. Configure webhooks in the dashboard or via the admin API.

| Event Type | Fired When | |---|---| | governance.decision | A governance decision is rendered | | trust.score_changed | Agent trust score changes | | trust.tier_changed | Agent trust tier changes | | proof.recorded | A proof record is committed | | alert.triggered | A compliance alert fires |

All webhook payloads include an HMAC-SHA256 signature in the X-Cognigate-Signature header for verification.

Next Steps

All Documentation