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_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

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

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.

Open Settings, API keys

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

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.

Store it securely

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

API keys read customer data. Never commit them to version control or ship them in public client side code. See API keys and authentication.

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 orwel_sk_YOUR_KEY"

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

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
$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:

{
  "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 orwel_sk_YOUR_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 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);

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

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

SDK

Developers

Integrations

Agents

Core Concepts

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