Quickstart

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.

npx skills add hyperlabs-ai/hyper-skills/orwel

Then just describe what you want. A few examples:

Add Orwel tracking to this project. Key: orwel_pk_xxxxxxxxxxxxxxxx

Track quote creation in the quote builder with Orwel, including the amount and currency.

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

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

Prefer to wire it by hand? Follow the SDK guide for manual installation and initialization.

Get Your API Key

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

Navigate to Settings

Go to your workspace settings in the Orwel dashboard

Generate API Key

Click on “API Keys” and generate a new key. You can create both production and development keys.

Store Securely

Copy your API key and store it securely. Never expose it in client-side code.

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

Make Your First Request

Let’s fetch your workspace leads using cURL:

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

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);

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
$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);
?>

Response Format

All successful responses follow this structure:

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

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"
    }
  }'

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);

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)

Next Steps

Authentication

Learn about API key types and security

API Reference

Explore all available endpoints

Rate Limiting

Understand rate limits

Error Handling

Handle errors gracefully

Get Started

Core Concepts

SDK

Set up with AI

Get Your API Key

Make Your First Request

Response Format

Response Headers

Create a Resource

Next Steps

Authentication

API Reference

Rate Limiting

Error Handling

​Set up with AI

​Get Your API Key

​Make Your First Request

​Response Format

​Response Headers

​Create a Resource

​Next Steps

Authentication

API Reference

Rate Limiting

Error Handling

Set up with AI

Get Your API Key

Make Your First Request

Response Format

Response Headers

Create a Resource

Next Steps