> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clix.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Complete reference for Clix API endpoints

The Clix API enables programmatic control of user management, messaging, campaign execution, and event tracking through server-to-server communication. Built on REST principles, it provides reliable endpoints designed to scale with your engagement needs.

### What You Can Do

With the Clix API, you can:

* **Manage Users** - Create, update, and delete project users; store and update custom user properties for segmentation and personalization
* **Send Messages** - Deliver push notifications directly to user devices with custom content
* **Trigger Campaigns** - Trigger pre-configured campaigns to specific users or broadcast to your entire user base

## Base URL

```
https://api.clix.so
```

All API requests must use HTTPS (TLS 1.2+) and be directed to the base URL above.

## Authentication

Every Clix API request requires authentication through two custom headers that identify your project and authorize the request:

| Header              | Required | Description                                        |
| ------------------- | -------- | -------------------------------------------------- |
| `X-Clix-Project-ID` | Yes      | Your project's unique identifier                   |
| `X-Clix-API-Key`    | Yes      | Your API key (public or secret based on operation) |

### API Key Types and Use Cases

Clix distinguishes between two API key types to provide flexibility and security:

| Key Type           | When to Use                                                       | Visibility             |
| ------------------ | ----------------------------------------------------------------- | ---------------------- |
| **Public API Key** | Client-side SDKs in mobile apps, browsers, or public environments | Safe to expose         |
| **Secret API Key** | Server-to-server communication, secure backend operations         | Must keep confidential |

### Key Selection Guide

* **Public Key**: Use for direct SDK integrations where your application frontend communicates with Clix
* **Secret Key**: Use for sensitive operations including user management, message sending, and campaign triggering

### Example Request

```bash theme={null}
curl -X POST https://api.clix.so/api/v1/users \
  -H "X-Clix-Project-ID: your_project_id" \
  -H "X-Clix-API-Key: your_secret_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "user": {
      "project_user_id": "user_123"
    }
  }'
```

### Protecting Your API Keys

<Warning>
  Secret API keys grant access to your project data and operations. Do not expose them in client-side code, version control repositories, or unencrypted logs. Key compromise may lead to unauthorized data access or operations.
</Warning>

* Store keys in environment variables or dedicated secrets management platforms
* Implement key rotation policies in your organization
* Apply the principle of least privilege—use Public keys in client applications, Secret keys only in trusted backends
* Regularly audit API key usage and revoke unused keys
* Enable alerts if unusual API activity is detected

## Rate Limits

Rate limits are applied to ensure fair usage and maintain service stability. If you exceed your rate limit, the API will return a `429 Too Many Requests` response.

For detailed information about rate limiting policies and best practices, see [Rate Limits](/api-reference/rate-limits).

## Content Type

The Clix API exclusively uses JSON for request and response bodies.

```
Content-Type: application/json
```

## Response Codes and Error Handling

Clix API responses follow standard HTTP conventions. The status code indicates the outcome of your request:

### Success Codes

| Status Code | Meaning | Notes                                                       |
| ----------- | ------- | ----------------------------------------------------------- |
| `200`       | OK      | Request processed successfully, response body contains data |
| `201`       | Created | Resource successfully created (e.g., new user)              |

### Client Error Codes

| Status Code | Meaning           | What to Do                                                                               |
| ----------- | ----------------- | ---------------------------------------------------------------------------------------- |
| `400`       | Bad Request       | Check request parameters, headers, and body format. Refer to endpoint documentation.     |
| `401`       | Unauthorized      | Verify API key and Project ID are correct and valid                                      |
| `404`       | Not Found         | The resource (user, campaign, etc.) doesn't exist. Verify the resource ID.               |
| `429`       | Too Many Requests | Rate limit exceeded. See [Rate Limits](/api-reference/rate-limits) for retry strategies. |

### Server Error Codes

| Status Code | Meaning               | What to Do                                                       |
| ----------- | --------------------- | ---------------------------------------------------------------- |
| `500`       | Internal Server Error | Temporary server issue. Implement exponential backoff and retry. |
| `503`       | Service Unavailable   | Scheduled maintenance or temporary outage. Retry after a delay.  |

### Error Response Format

When a request fails, the response body contains an error message:

```json theme={null}
{
  "error": "Invalid project user ID format"
}
```

### Implementing Reliable Retries

For production integrations, implement exponential backoff to handle transient failures gracefully:

```javascript theme={null}
async function makeRequestWithRetry(url, options, maxAttempts = 3) {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    try {
      const response = await fetch(url, options);

      // Don't retry client errors (4xx) - they won't succeed with retry
      if (response.status < 500) {
        return response;
      }

      // On last attempt, throw the error
      if (attempt === maxAttempts - 1) {
        throw new Error(`Server error: ${response.status}`);
      }

      // Calculate exponential backoff: 1s, 2s, 4s, etc.
      const delayMs = Math.pow(2, attempt) * 1000;
      await new Promise(resolve => setTimeout(resolve, delayMs));
    } catch (error) {
      if (attempt === maxAttempts - 1) throw error;
    }
  }
}
```

## OpenAPI Specification

The complete OpenAPI specification for the Clix API is available:

<Card title="OpenAPI Spec" icon="file-code" href="/api-reference/openapi.json">
  View the complete OpenAPI specification
</Card>

## API Endpoints

### Users

Store and manage your project's user profiles. Users can have custom properties used for segmentation, personalization, and targeting.

* [Create User](/api-reference/endpoint/users/create) - Register a new project user
* [Update User](/api-reference/endpoint/users/update) - Modify user properties and attributes
* [Delete User](/api-reference/endpoint/users/delete) - Permanently remove a user from your project

### Campaigns

Campaigns are pre-configured message templates set up in your dashboard. Use the API to trigger campaigns to reach your users.

* [Trigger Campaign](/api-reference/endpoint/campaigns:trigger) - Execute a campaign, targeting specific users or broadcast to all users matching campaign filters

### Messages

Send ad-hoc push notifications outside of campaigns. Useful for transactional or time-sensitive messages.

* [Send Messages](/api-reference/endpoint/messages:send) - Deliver push notifications directly to specified devices

## SDK Integration

For easier integration, consider using our official SDKs:

* [iOS SDK](/sdk-quickstart-ios)
* [Android SDK](/sdk-quickstart-android)
* [React Native SDK](/sdk-quickstart-react-native)
* [Flutter SDK](/sdk-quickstart-flutter)

## Request Timeout

API requests have a maximum execution time of **100 seconds**. If your request doesn't complete within this window, it will be terminated with a timeout error. Ensure your integration handles timeouts gracefully.

## Integration Guidelines

Build robust integrations with these recommendations:

* **Always use HTTPS** - Connections must be encrypted with TLS 1.2 or higher
* **Implement exponential backoff** - Automatically retry on 5xx errors with increasing delays (1s, 2s, 4s...)
* **Respect rate limits** - Monitor response status and throttle requests to stay within limits
* **Log responses** - Track API responses for debugging and monitoring
* **Validate inputs** - Check that project user IDs and other identifiers match expected formats
* **Choose keys wisely** - Use Public keys for SDKs, Secret keys only for backend services

For rate limiting specifics and strategies, see the [Rate Limits](/api-reference/rate-limits) guide.

## Support

Need help? Contact our support team:

* Email: [support@clix.so](mailto:support@clix.so)
* Documentation: [https://docs.clix.so](https://docs.clix.so)