> ## Documentation Index
> Fetch the complete documentation index at: https://www.orwel.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Start using Orwel in about 2 minutes: set it up with AI, or call the API directly.

There are two ways to get going: let an **AI assistant** wire Orwel for you from a prompt (the fastest path, and where most setups are headed), or work with the **API** directly.

## Set up with AI

Install the Orwel agent skill once. Your assistant (e.g. Claude Code) then knows the whole SDK (install, init, tracking and conversions) and writes correct code from a plain-language prompt.

```bash theme={null}
npx skills add hyperlabs-ai/hyper-skills/orwel
```

Then just describe what you want. A few examples:

```text Install & track theme={null}
Add Orwel tracking to this project. Key: orwel_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
```

```text Track a feature theme={null}
Track quote creation in the quote builder with Orwel, including the amount and currency.
```

```text Capture a conversion theme={null}
Fire an Orwel conversion when the signup form submits, with the selected plan as a property.
```

> [!TIP]
>
> The skill follows **Rule 0** (it reads the key from an environment variable per framework and never hardcodes it) and knows the SDK's validation rules, so generated calls are correct and safe by default. Details on the [AI Skill](https://www.orwel.io/docs/sdk/ai-skill.md) page.

> [!NOTE]
>
> Prefer to wire it by hand? Follow the [SDK guide](https://www.orwel.io/docs/sdk/introduction.md) for manual installation and initialization.

## Get Your API Key

Your site sends data with the **production API key** (`orwel_...`), which the SDK uses. To call the REST API you need an **API key** (`orwel_sk_...`), which can read data.

**1. Open Settings, API keys**

Go to your workspace settings in the Orwel dashboard and open **API keys**.

**2. Create an API key**

Name it, choose the scopes it needs (for example `leads:read`), and choose **server only** unless a browser app will call the API from an allowed origin.

**3. Store it securely**

Copy the key (it is shown once) and keep it in an environment variable or a secret manager.

> [!WARNING]
>
> API keys read customer data. Never commit them to version control or ship them in public client side code. See [API keys and authentication](https://www.orwel.io/docs/authentication.md).

## Make Your First Request

Let's fetch your workspace leads using cURL:

```bash cURL theme={null}
curl -X GET "https://api.orwel.io/api/v1/leads?limit=10" \
  -H "Authorization: Bearer orwel_sk_YOUR_KEY"
```

```javascript JavaScript theme={null}
const response = await fetch('https://api.orwel.io/api/v1/leads?limit=10', {
  headers: {
    'Authorization': 'Bearer orwel_sk_YOUR_KEY'
  }
});

const data = await response.json();
console.log(data);
```

```python Python theme={null}
import requests

headers = {
    'Authorization': 'Bearer orwel_sk_YOUR_KEY'
}

response = requests.get(
    'https://api.orwel.io/api/v1/leads',
    headers=headers,
    params={'limit': 10}
)

data = response.json()
print(data)
```

```php PHP theme={null}
<?php
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://api.orwel.io/api/v1/leads?limit=10');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer orwel_sk_YOUR_KEY'
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data);
?>
```

## Response Format

All successful responses follow this structure:

```json theme={null}
{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "visitor_id": "660e8400-e29b-41d4-a716-446655440001",
      "workspace_id": "770e8400-e29b-41d4-a716-446655440002",
      "code": "lead_001",
      "source": "website",
      "created_at": "2025-01-15T10:30:00Z",
      "properties": {
        "industry": "technology"
      }
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "total": 150
  }
}
```

## Response Headers

Every response includes useful headers:

```
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1642252800
X-Workspace-Id: 770e8400-e29b-41d4-a716-446655440002
```

## Create a Resource

Let's create a new visitor identity:

```bash cURL theme={null}
curl -X POST "https://api.orwel.io/api/v1/identities" \
  -H "Authorization: Bearer orwel_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "name": "John Doe",
    "traits": {
      "plan": "enterprise",
      "company": "Acme Corp"
    }
  }'
```

```javascript JavaScript theme={null}
const response = await fetch('https://api.orwel.io/api/v1/identities', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer orwel_sk_YOUR_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: 'user@example.com',
    name: 'John Doe',
    traits: {
      plan: 'enterprise',
      company: 'Acme Corp'
    }
  })
});

const data = await response.json();
console.log(data);
```

```python Python theme={null}
import requests
import json

headers = {
    'Authorization': 'Bearer orwel_sk_YOUR_KEY',
    'Content-Type': 'application/json'
}

payload = {
    'email': 'user@example.com',
    'name': 'John Doe',
    'traits': {
        'plan': 'enterprise',
        'company': 'Acme Corp'
    }
}

response = requests.post(
    'https://api.orwel.io/api/v1/identities',
    headers=headers,
    data=json.dumps(payload)
)

data = response.json()
print(data)
```

## Next Steps

> [card] [Authentication](https://www.orwel.io/docs/authentication.md)
>
> Learn about API key types and security

> [card] [API Reference](https://www.orwel.io/docs/api-reference/introduction.md)
>
> Explore all available endpoints

> [card] [Rate Limiting](https://www.orwel.io/docs/concepts/rate-limiting.md)
>
> Understand rate limits

> [card] [Error Handling](https://www.orwel.io/docs/concepts/errors.md)
>
> Handle errors gracefully


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.