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

# API Reference

> Complete reference for the Orwel API

## Base URL

All API requests should be made to:

```
https://api.orwel.io/api/v1
```

## Authentication

Call the API with an **API key** (`orwel_sk_...`) created in **Settings, API keys**, sent as a Bearer token:

```bash theme={null}
Authorization: Bearer orwel_sk_YOUR_KEY
```

Each key carries scopes (`leads:read`, `visitors:read`, `companies:read`, `campaigns:read`, `conversions:read`, `leads:write`, `lists:write`, `mcp`) and either a list of allowed origins or server only access. The production API key that the SDK uses (`orwel_...`) and the development key (`orwel_dev_...`) only send data and are rejected here. See [API keys and authentication](https://www.orwel.io/docs/authentication.md).

## Available Resources

> [card] [Leads](https://www.orwel.io/docs/api-reference/leads/list.md)
>
> Manage and track leads in your workspace

> [card] [Users](https://www.orwel.io/docs/api-reference/users/list.md)
>
> Access workspace members and their information

> [card] [Identities](https://www.orwel.io/docs/api-reference/identities/list.md)
>
> Manage visitor identities and their traits

> [card] [Companies](https://www.orwel.io/docs/api-reference/companies/list.md)
>
> Companies enriched from your leads

> [card] [Visitor Lists](https://www.orwel.io/docs/api-reference/lists/list.md)
>
> Segments of visitors

> [card] [Conversions](https://www.orwel.io/docs/api-reference/conversions/list.md)
>
> Every conversion with its lead, to sync without duplicates

> [card] [Campaigns](https://www.orwel.io/docs/api-reference/campaigns/list.md)
>
> Ad campaigns with cost, clicks and conversions

> [card] [Reports](https://www.orwel.io/docs/api-reference/reports/create.md)
>
> Metrics and a written analysis for a date range

## Scopes per endpoint

| Endpoint | Scope |
| - | - |
| `GET /leads`, `GET /leads/{id}` | `leads:read` |
| `POST /leads`, `PATCH /leads/{id}` | `leads:write` |
| `GET /users`, `GET /users/{id}` | `leads:read` |
| `GET /identities`, `GET /identities/{id}`, `/activity`, `/personalities` | `visitors:read` |
| `POST /identities`, `PATCH /identities/{id}` | `leads:write` |
| `GET /companies`, `GET /companies/{id}` | `companies:read` |
| `GET /lists` | `visitors:read` |
| `GET /conversions`, `GET /conversions/{id}` | `conversions:read` |
| `GET /campaigns` | `campaigns:read` |
| `POST /reports` | `leads:read` + `visitors:read` + `conversions:read` |

## Request Format

All `POST` and `PATCH` requests should include a `Content-Type: application/json` header and a JSON body.

```bash theme={null}
curl -X POST "https://api.orwel.io/api/v1/leads" \
  -H "Authorization: Bearer orwel_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code": "lead_001", "source": "website"}'
```

## Response Format

All responses are returned in JSON format with the following structure:

### Success Response

```json theme={null}
{
  "data": { ... },
  "pagination": { ... }  // Only for list endpoints
}
```

### Error Response

```json theme={null}
{
  "error": "error_code",
  "message": "Human readable error message",
  "details": { ... }  // Optional additional context
}
```

## HTTP Status Codes

**200** `OK`

Request succeeded

**201** `Created`

Resource created successfully

**400** `Bad Request`

Invalid request parameters

**401** `Unauthorized`

Invalid or missing API key

**403** `Forbidden`

The key lacks the scope (`insufficient_scope`), the browser origin is not allowed (`origin_not_allowed`), or the plan does not include the feature (`plan_not_allowed`). See [Errors](https://www.orwel.io/docs/concepts/errors.md).

**404** `Not Found`

Resource not found

**429** `Too Many Requests`

Rate limit exceeded

**500** `Internal Server Error`

Server error

## Pagination

List endpoints support pagination using `limit` and `offset` parameters:

```bash theme={null}
GET /api/v1/leads?limit=50&offset=100
```

Response includes pagination metadata:

```json theme={null}
{
  "data": [...],
  "pagination": {
    "limit": 50,
    "offset": 100,
    "total": 500
  }
}
```

**Limits:**

* Default: 50 items
* Maximum: 100 items per request

## Filtering

Many endpoints support filtering via query parameters:

```bash theme={null}
# Filter leads by source
GET /api/v1/leads?source=website

# Filter by date range
GET /api/v1/leads?created_after=2025-01-01T00:00:00Z&created_before=2025-01-31T23:59:59Z

# Combine filters
GET /api/v1/identities?email=user@example.com&is_favorite=true
```

## Rate Limiting

All requests are subject to rate limiting. Check the response headers:

```
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1642252800
```

See [Rate Limiting](https://www.orwel.io/docs/concepts/rate-limiting.md) for details.

## Timestamps

All timestamps are in ISO 8601 format with UTC timezone:

```
2025-01-15T10:30:00Z
```

## UUIDs

All resource IDs are UUIDs in the format:

```
550e8400-e29b-41d4-a716-446655440000
```

## JSONB Fields

Some fields accept arbitrary JSON objects (properties, traits, etc.):

```json theme={null}
{
  "properties": {
    "custom_field": "value",
    "nested": {
      "data": true
    }
  }
}
```

## Workspace Scoping

All API requests are automatically scoped to your workspace. You can only access data that belongs to your organization.

The workspace ID is included in response headers:

```
X-Workspace-Id: 770e8400-e29b-41d4-a716-446655440002
```

## SDKs and Libraries

> [card] JavaScript/TypeScript
>
> Coming soon

> [card] Python
>
> Coming soon

> [card] PHP
>
> Coming soon

> [card] Ruby
>
> Coming soon

## Need Help?

> [card] [Support](https://www.orwel.io/docs/support.md)
>
> Email the Orwel team

> [card] [Book a session](https://calendar.app.google/PK9jFSscVpemopQ76)
>
> 30 minutes to review your setup


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