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

# API Reference

> Complete reference for the Orwel API

## Base URL

All API requests should be made to:

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

## Authentication

Include your API key in every request using the `Authorization` header:

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

See the [Authentication](/authentication) guide for more details.

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

<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 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](/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 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

<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="mailto:support@orwel.io">
    Email our support team
  </Card>

  <Card title="Community" icon="slack" href="https://orwel.io/community">
    Join our Slack community
  </Card>
</CardGroup>