API Documentation

Everything you need to integrate ConsentGate with your AI agent.

Quick Start

1. Get an API Key

2. Create Rules

Define what actions should be allowed, denied, or require approval in the rules dashboard.

3. Check Before Acting

Call the API before your agent performs sensitive actions.

Authentication

All API requests require a Bearer token in the Authorization header:

Authorization: Bearer cg_your_api_key_here

API keys start with cg_. Keep your keys secret!

Endpoints

POST/api/v1/check-action

Check if an action is allowed based on user's consent rules.

Request Body

{
  "action": "send_email",           // Required: What the agent wants to do
  "category": "email",              // Required: Action category
  "metadata": {                     // Optional: Additional context for rules
    "recipient": "boss@company.com",
    "subject": "Project Update"
  }
}

Response

{
  "allowed": true,                  // Boolean: Can the agent proceed?
  "decision": "allow",              // "allow" | "deny" | "ask"
  "reason": "Rule: Allow work emails",
  "rule_id": "rule_abc123",         // ID of matched rule (if any)
  "checked_at": "2026-02-12T18:00:00.000Z"
}

Example

curl -X POST https://consent.agentz.fyi/api/v1/check-action \
  -H "Authorization: Bearer cg_xxx" \
  -H "Content-Type: application/json" \
  -d '{"action": "send_email", "category": "email"}'

GET/api/v1/rules

List all consent rules for the authenticated user.

// Response
{
  "rules": [
    {
      "id": "rule_abc123",
      "name": "Allow work emails",
      "category": "email",
      "decision": "allow",
      "priority": 10,
      "enabled": true,
      "conditions": [
        {"field": "recipient", "operator": "contains", "value": "@company.com"}
      ]
    }
  ],
  "count": 1
}

GET/api/v1/audit

Retrieve audit log of consent checks. Supports pagination and filtering.

Query Parameters

category - Filter by action category
decision - Filter by decision (allow/deny/ask)
from - Start date (ISO 8601)
to - End date (ISO 8601)
limit - Results per page (max 100)
offset - Pagination offset

Action Categories

Built-in categories for common agent actions:

social_post

message

file_write

file_delete

api_call

spending

calendar

system

custom

Use custom for any category not listed, or * to match all categories.

Condition Operators

Use these operators in rule conditions:

Operator	Description	Example
equals	Exact match	recipient equals "boss@co.com"
contains	String contains	recipient contains "@company.com"
gt / lt / gte / lte	Numeric comparison	amount gt 100
in	Value in list	category in ["email", "message"]
regex	Regex match	subject regex "^URGENT:"

Error Codes

Code	HTTP Status	Description
UNAUTHORIZED	401	Missing Authorization header
INVALID_KEY	401	API key not found
KEY_REVOKED	401	API key has been revoked
INVALID_BODY	400	Request body is not valid JSON
RATE_LIMITED	429	Too many requests

SDKs & Examples

Official SDKs coming soon. For now, use any HTTP client:

Python

import requests

response = requests.post(
    "https://consent.agentz.fyi/api/v1/check-action",
    headers={"Authorization": "Bearer cg_xxx"},
    json={"action": "send_email", "category": "email"}
)

if response.json()["allowed"]:
    # Proceed with action
    send_email()
else:
    # Handle denial or ask for approval
    print(response.json()["reason"])

JavaScript/TypeScript

const response = await fetch("https://consent.agentz.fyi/api/v1/check-action", {
  method: "POST",
  headers: {
    "Authorization": "Bearer cg_xxx",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ action: "send_email", category: "email" })
});

const { allowed, decision, reason } = await response.json();

if (allowed) {
  await sendEmail();
} else {
  console.log(`Action blocked: ${reason}`);
}