Quick Start Guide

Get up and running with GovernanceAI in just 5 minutes. We’ll walk you through creating an organization, generating an API key, and making your first guardrail evaluation.

Prerequisites

• An active GovernanceAI account (SaaS or On-Premise)
• A terminal with cURL, Python, or Node.js installed
• 5 minutes of your time

Step 1: Log In & Access Dashboard (1 min)

For SaaS:

• Visit app.governanceai.com
• Click Sign In
• Enter your credentials
• You’ll land on your organization dashboard

For On-Premise:

• Visit your instance URL (e.g., https://governanceai.your-domain.com)
• Log in with your credentials

Step 2: Generate Your First API Key (1 min)

• Click your avatar (top right) → Settings
• Navigate to API Keys
• Click Create New API Key
• Fill in:
  • Name: My First Key
  • Environment: Production
  • Scope: Select runtime:execute (for making guardrail calls)
• Click Generate

⚠️ Copy the API key immediately - You won’t see it again!

gak_prod_1234567890abcdefghijklmnopqr

Save it to your environment:

$
export GOVERNANCEAI_API_KEY="gak_prod_1234567890abcdefghijklmnopqr"

Step 3: Get Your Organization ID (1 min)

• Stay in Settings page
• Look for Organization Details section
• Copy your Organization ID (looks like org_123abc...)

$
export GOVERNANCEAI_ORG_ID="org_123abc..."

Step 4: Make Your First API Call (1 min)

Choose your preferred language:

Option A: cURL

$
curl -X POST https://api.governanceai.com/v1/guardrails/evaluate \
>
  -H "Authorization: Bearer $GOVERNANCEAI_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "messages": [
>
      {
>
        "role": "user",
>
        "content": "What is the capital of France?"
>
      }
>
    ],
>
    "context": {
>
      "org_id": "'$GOVERNANCEAI_ORG_ID'",
>
      "user_id": "user_demo",
>
      "session_id": "session_123"
>
    }
>
  }'

Option B: Python

1
import requests
2
import os
3
4
api_key = os.getenv('GOVERNANCEAI_API_KEY')
5
org_id = os.getenv('GOVERNANCEAI_ORG_ID')
6
7
response = requests.post(
8
    'https://api.governanceai.com/v1/guardrails/evaluate',
9
    headers={
10
        'Authorization': f'Bearer {api_key}',
11
        'Content-Type': 'application/json'
12
    },
13
    json={
14
        'messages': [
15
            {
16
                'role': 'user',
17
                'content': 'What is the capital of France?'
18
            }
19
        ],
20
        'context': {
21
            'org_id': org_id,
22
            'user_id': 'user_demo',
23
            'session_id': 'session_123'
24
        }
25
    }
26
)
27
28
print(response.json())

Option C: Node.js

1
const https = require('https');
2
3
const apiKey = process.env.GOVERNANCEAI_API_KEY;
4
const orgId = process.env.GOVERNANCEAI_ORG_ID;
5
6
const options = {
7
  hostname: 'api.governanceai.com',
8
  path: '/v1/guardrails/evaluate',
9
  method: 'POST',
10
  headers: {
11
    'Authorization': `Bearer ${apiKey}`,
12
    'Content-Type': 'application/json'
13
  }
14
};
15
16
const req = https.request(options, (res) => {
17
  let data = '';
18
  res.on('data', (chunk) => { data += chunk; });
19
  res.on('end', () => { console.log(JSON.parse(data)); });
20
});
21
22
req.write(JSON.stringify({
23
  messages: [
24
    {
25
      role: 'user',
26
      content: 'What is the capital of France?'
27
    }
28
  ],
29
  context: {
30
    org_id: orgId,
31
    user_id: 'user_demo',
32
    session_id: 'session_123'
33
  }
34
}));
35
36
req.end();

Step 5: Review the Response (1 min)

You should receive a response like:

1
{
2
  "decision": "allow",
3
  "policy_violations": [],
4
  "risk_score": 0.05,
5
  "metadata": {
6
    "evaluation_time_ms": 45,
7
    "policies_evaluated": 12,
8
    "org_id": "org_123abc..."
9
  }
10
}

Response Fields:

• decision - Whether the message was allowed or blocked
• policy_violations - List of policies that were violated (if any)
• risk_score - Overall risk score (0-1, where 1 is highest risk)
• metadata - Additional info about the evaluation

Understanding the Response

If decision is “allow” ✅

Your message passed all active guardrails. The LLM response is safe to display to the user.

1
{
2
  "decision": "allow",
3
  "policy_violations": [],
4
  "risk_score": 0.02
5
}

If decision is “block” ❌

Your message violated one or more policies. You should not display the response to the user.

1
{
2
  "decision": "block",
3
  "policy_violations": [
4
    {
5
      "policy_id": "policy_toxicity",
6
      "policy_name": "Block Toxic Content",
7
      "severity": "high"
8
    }
9
  ],
10
  "risk_score": 0.92
11
}

If decision is “transform”

The message was modified to comply with policies before being returned.

1
{
2
  "decision": "transform",
3
  "policy_violations": ["policy_pii_redaction"],
4
  "transformed_response": "The person is located in [REDACTED]",
5
  "risk_score": 0.15
6
}

Next Steps

Congratulations! 🎉

You’ve successfully made your first GovernanceAI API call. Here’s what to explore next:

• Set Up Guardrails

  • Create custom guardrails specific to your use case
  • Configure policy rules and thresholds

• Create Policies

  • Define organization-wide governance policies
  • Test policies before rolling out to production

• Integrate with Your Stack

  • Connect with GitHub for code scanning
  • Set up Jira for issue tracking
  • Integrate with your favorite LLM provider

• Code Examples

  • Python client library setup
  • Node.js integration patterns
  • Advanced API patterns

• Core Concepts

  • Deep dive into guardrails and policies
  • Learn about AI Bill of Materials
  • Understand red-teaming framework

Common Issues

Error: 401 Unauthorized

Problem: Invalid or missing API key

Solution:

• Verify your API key is correct
• Make sure it hasn’t been rotated
• Check the Authorization header format: Authorization: Bearer <key>

Error: 403 Forbidden

Problem: API key doesn’t have permission

Solution:

• Go to Settings → API Keys
• Verify your key has runtime:execute scope
• Generate a new key with correct permissions

Error: Network timeout

Problem: Connection to API is slow

Solution:

• Check your internet connection
• Try again in a few seconds
• Contact support if issue persists

Troubleshooting Checklist

• API key is correct and starts with gak_
• Organization ID is correct and starts with org_
• Using HTTPS (not HTTP)
• Authorization header format is correct
• API key has runtime:execute scope
• API key hasn’t expired
• Network can reach api.governanceai.com
• Request body is valid JSON

Need Help?

• 📖 Full API Reference - Complete endpoint documentation
• 💻 Code Examples - More code samples
• 📞 Support & Community - Get help from our team
• 🏗️ Architecture Overview - Understand how it works

You’re all set! Start building with GovernanceAI. 🚀