> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.governanceaicore.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.governanceaicore.com/_mcp/server.

# Quick Start Guide

> Get started with GovernanceAI in 5 minutes with your first API call

# 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](https://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:

```bash
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...`)

```bash
export GOVERNANCEAI_ORG_ID="org_123abc..."
```

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

Choose your preferred language:

### Option A: cURL

```bash
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

```python
import requests
import os

api_key = os.getenv('GOVERNANCEAI_API_KEY')
org_id = os.getenv('GOVERNANCEAI_ORG_ID')

response = requests.post(
    'https://api.governanceai.com/v1/guardrails/evaluate',
    headers={
        'Authorization': f'Bearer {api_key}',
        'Content-Type': 'application/json'
    },
    json={
        'messages': [
            {
                'role': 'user',
                'content': 'What is the capital of France?'
            }
        ],
        'context': {
            'org_id': org_id,
            'user_id': 'user_demo',
            'session_id': 'session_123'
        }
    }
)

print(response.json())
```

### Option C: Node.js

```javascript
const https = require('https');

const apiKey = process.env.GOVERNANCEAI_API_KEY;
const orgId = process.env.GOVERNANCEAI_ORG_ID;

const options = {
  hostname: 'api.governanceai.com',
  path: '/v1/guardrails/evaluate',
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  }
};

const req = https.request(options, (res) => {
  let data = '';
  res.on('data', (chunk) => { data += chunk; });
  res.on('end', () => { console.log(JSON.parse(data)); });
});

req.write(JSON.stringify({
  messages: [
    {
      role: 'user',
      content: 'What is the capital of France?'
    }
  ],
  context: {
    org_id: orgId,
    user_id: 'user_demo',
    session_id: 'session_123'
  }
}));

req.end();
```

## Step 5: Review the Response (1 min)

You should receive a response like:

```json
{
  "decision": "allow",
  "policy_violations": [],
  "risk_score": 0.05,
  "metadata": {
    "evaluation_time_ms": 45,
    "policies_evaluated": 12,
    "org_id": "org_123abc..."
  }
}
```

**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.

```json
{
  "decision": "allow",
  "policy_violations": [],
  "risk_score": 0.02
}
```

### If `decision` is "block" ❌

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

```json
{
  "decision": "block",
  "policy_violations": [
    {
      "policy_id": "policy_toxicity",
      "policy_name": "Block Toxic Content",
      "severity": "high"
    }
  ],
  "risk_score": 0.92
}
```

### If `decision` is "transform"

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

```json
{
  "decision": "transform",
  "policy_violations": ["policy_pii_redaction"],
  "transformed_response": "The person is located in [REDACTED]",
  "risk_score": 0.15
}
```

## Next Steps

### Congratulations! 🎉

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

* **[Set Up Guardrails](../guides/setting-up-guardrails.mdx)**
  * Create custom guardrails specific to your use case
  * Configure policy rules and thresholds

* **[Create Policies](../guides/creating-policies.mdx)**
  * Define organization-wide governance policies
  * Test policies before rolling out to production

* **[Integrate with Your Stack](../integrations/)**
  * Connect with GitHub for code scanning
  * Set up Jira for issue tracking
  * Integrate with your favorite LLM provider

* **[Code Examples](/code-examples/)**
  * Python client library setup
  * Node.js integration patterns
  * Advanced API patterns

* **[Core Concepts](/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](/api) - Complete endpoint documentation
* 💻 [Code Examples](/code-examples/) - More code samples
* 📞 [Support & Community](../support.mdx) - Get help from our team
* 🏗️ [Architecture Overview](./02-architecture-overview.mdx) - Understand how it works

---

**You're all set!** Start building with GovernanceAI. 🚀