> ## Documentation Index
> Fetch the complete documentation index at: https://orwel-22af1265.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Start using Orwel in under 5 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:

<CodeGroup>
  ```text Install & track theme={null}
  Add Orwel tracking to this project. Key: orwel_pk_xxxxxxxxxxxxxxxx
  ```

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

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

## Get Your API Key

First, you need to obtain your API key from the Orwel dashboard.

<Steps>
  <Step title="Navigate to Settings">
    Go to your workspace settings in the Orwel dashboard
  </Step>

  <Step title="Generate API Key">
    Click on "API Keys" and generate a new key. You can create both production and development keys.
  </Step>

  <Step title="Store Securely">
    Copy your API key and store it securely. Never expose it in client-side code.
  </Step>
</Steps>

<Warning>
  API keys are sensitive credentials. Never commit them to version control or expose them in client-side code.
</Warning>

## Make Your First Request

Let's fetch your workspace leads using cURL:

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

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

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

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

  headers = {
      'Authorization': 'Bearer YOUR_API_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 YOUR_API_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 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:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.orwel.io/api/v1/identities" \
    -H "Authorization: Bearer YOUR_API_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 YOUR_API_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 YOUR_API_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>