# 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
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_pk_...`) and the development key (`orwel_dev_...`) only send data and are rejected here. See [API keys and authentication](/docs/authentication).

## Available Resources

<CardGroup cols={3}>
  <Card title="Leads" icon="user-plus" href="/api-reference/leads/list">
    Manage and track leads in your workspace
  </Card>
  <Card title="Users" icon="users" href="/api-reference/users/list">
    Access workspace members and their information
  </Card>
  <Card title="Identities" icon="id-card" href="/api-reference/identities/list">
    Manage visitor identities and their traits
  </Card>
</CardGroup>

## Request Format

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

```bash
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
{
  "data": { ... },
  "pagination": { ... }  // Only for list endpoints
}
```

### Error Response

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

## HTTP Status Codes

<ResponseField name="200" type="OK">
  Request succeeded
</ResponseField>

<ResponseField name="201" type="Created">
  Resource created successfully
</ResponseField>

<ResponseField name="400" type="Bad Request">
  Invalid request parameters
</ResponseField>

<ResponseField name="401" type="Unauthorized">
  Invalid or missing API key
</ResponseField>

<ResponseField name="403" type="Forbidden">
  Access denied to resource
</ResponseField>

<ResponseField name="404" type="Not Found">
  Resource not found
</ResponseField>

<ResponseField name="429" type="Too Many Requests">
  Rate limit exceeded
</ResponseField>

<ResponseField name="500" type="Internal Server Error">
  Server error
</ResponseField>

## Pagination

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

```bash
GET /api/v1/leads?limit=50&offset=100
```

Response includes pagination metadata:

```json
{
  "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
# 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](/docs/concepts/rate-limiting) 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
{
  "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

<CardGroup cols={2}>
  <Card title="JavaScript/TypeScript" icon="js">
    Coming soon
  </Card>
  <Card title="Python" icon="python">
    Coming soon
  </Card>
  <Card title="PHP" icon="php">
    Coming soon
  </Card>
  <Card title="Ruby" icon="gem">
    Coming soon
  </Card>
</CardGroup>

## Need Help?

<CardGroup cols={2}>
  <Card title="Support" icon="envelope" href="/support">
    Email the Orwel team
  </Card>
  <Card title="Book a session" icon="calendar" href="https://calendar.app.google/PK9jFSscVpemopQ76">
    30 minutes to review your setup
  </Card>
</CardGroup>