# 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
npx skills add hyperlabs-ai/hyper-skills/orwel
```

Then just describe what you want. A few examples:

<CodeGroup>

```text Install & track
Add Orwel tracking to this project. Key: orwel_pk_xxxxxxxxxxxxxxxx
```

```text Track a feature
Track quote creation in the quote builder with Orwel, including the amount and currency.
```

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

</CodeGroup>

<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](/docs/sdk/ai-skill) page.
</Tip>

<Note>
  Prefer to wire it by hand? Follow the [SDK guide](/docs/sdk/introduction) for manual installation and initialization.
</Note>

## Get Your API Key

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

<Steps>
  <Step title="Open Settings, API keys">
    Go to your workspace settings in the Orwel dashboard and open **API keys**.
  </Step>
  <Step title="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.
  </Step>
  <Step title="Store it securely">
    Copy the key (it is shown once) and keep it in an environment variable or a secret manager.
  </Step>
</Steps>

<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](/docs/authentication).
</Warning>

## Make Your First Request

Let's fetch your workspace leads using cURL:

<CodeGroup>

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

```javascript JavaScript
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
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
<?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);
?>
```

</CodeGroup>

## Response Format

All successful responses follow this structure:

```json
{
  "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:

<CodeGroup>

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

</CodeGroup>

## Next Steps

<CardGroup cols={2}>
  <Card
    title="Authentication"
    icon="key"
    href="/authentication"
  >
    Learn about API key types and security
  </Card>
  <Card
    title="API Reference"
    icon="book"
    href="/api-reference/introduction"
  >
    Explore all available endpoints
  </Card>
  <Card
    title="Rate Limiting"
    icon="gauge"
    href="/concepts/rate-limiting"
  >
    Understand rate limits
  </Card>
  <Card
    title="Error Handling"
    icon="triangle-exclamation"
    href="/concepts/errors"
  >
    Handle errors gracefully
  </Card>
</CardGroup>