# HTTP API

### Base URL

```
https://api.raindrop.ai/v1
```

### Authentication

All API requests must include your SDK write key in the `Authorization` header:

```
Authorization: Bearer YOUR_WRITE_KEY
```

You can get your API key by logging in to [app.raindrop.ai](https://app.raindrop.ai) (bottom of the tab bar!).

### Endpoints

#### Track Event

Track any event, including AI interactions and normal analytics events.

**POST** `/events/track`

**Request Body**

(Must be provided as an array of objects)

| Field            | Type   | Description                                                                                        |
|-------------------|--------|----------------------------------------------------------------------------------------------------|
| `user_id`         | string | The unique identifier of the user                                                                  |
| `event`           | string | The name of the event you want to track                                                            |
| `properties`      | object | (Optional) Additional properties associated with the event                                         |
| `attachments`     | array  | (Optional) Array of attachments to include with the event                                          |
| `ai_data`        | object | (Optional) Object containing AI-specific data for AI events. **If provided, either input or output (or both) is required** |
| `ai_data.model`  | string | (Optional) The name of the AI model used                                                           |
| `ai_data.input`  | string | (Optional) The input provided by the user                                                          |
| `ai_data.output` | string | (Optional) The output generated by the AI                                                          |
| `ai_data.convo_id` | string | (Optional) The conversation ID associated with the interaction                                      |

**Example Request - AI Interaction**

```json
POST /v1/events/track HTTP/1.1
Host: api.raindrop.ai
Authorization: Bearer YOUR_WRITE_KEY
Content-Type: application/json

[
 {
 "user_id": "user123",
 "event": "ai_interaction",
 "properties": {
 "tool_call": "reasoning_engine",
 "system_prompt": "you are a helpful...",
 "experiment": "experiment_a"
 },
 "ai_data": {
 "model": "gpt_4",
 "input": "What is the weather like today?",
 "output": "The weather is sunny and warm.",
 "convo_id": "conv789"
 },
 "attachments": [
 {
 "type": "image",
 "value": "https://example.com/image.png",
 "role": "output"
 },
 {
 "type": "code",
 "name": "Example Code",
 "value": "console.log('Hello, World!');",
 "role": "input",
 "language": "javascript"
 }
 ]
 }
]
```

**Response**

All authorized requests will return a `204 Success` status code. For debugging failures, contact us: [founders@raindrop.ai](mailto:founders@raindrop.ai).

Event has a limit of 1 MB. Properties will be truncated for larger events. [Contact us](mailto:founders@raindrop.ai) if you have custom requirements.

#### Track Signal

Track positive or negative user signals such as thumbs up, thumbs down, output schema failures, user edits, regenerations, and other ground-truth signals about your AI product's performance. Each signal must be associated with an `event_id` for an event that was sent to Raindrop with the `/events/track` endpoint.

**POST** `/signals/track`

**Request Body**

(Must be provided as an array of objects)

| Field            | Type   | Description                                                                                        |
|-------------------|--------|----------------------------------------------------------------------------------------------------|
| `event_id`        | string | The event_id of the event that you sent to Raindrop                                               |
| `signal_name`     | string | The name of the signal (e.g., "thumbs_up", "thumbs_down")                                      |
| `timestamp`       | string | (Optional) ISO timestamp when the signal occurred                                                  |
| `properties`      | object | (Optional) Additional properties associated with the signal                                         |
| `attachment_id`   | string | (Optional) Reference to a previously sent attachment                                               |
| `signal_type`     | string | (Optional) Type of signal: "default", "feedback", "edit", or "standard"                     |
| `sentiment`       | string | (Optional) One of "POSITIVE" or "NEGATIVE"                                                     |

**Example Request**

```json
POST /v1/signals/track HTTP/1.1
Host: api.raindrop.ai
Authorization: Bearer YOUR_WRITE_KEY
Content-Type: application/json

[
 {
 "event_id": "123456789",
 "signal_name": "thumbs_up",
 "sentiment": "POSITIVE",
 "properties": {
 "location": "chat_ui"
 },
 "signal_type": "default"
 }
]
```

**Response**

All authorized requests will return a `204 Success` status code. For debugging failures, contact us: [founders@raindrop.ai](mailto:founders@raindrop.ai).

#### Identify User

Associate traits with a user.

**POST** `/users/identify`

**Request Body**

| Field            | Type   | Description                                                                                        |
|-------------------|--------|----------------------------------------------------------------------------------------------------|
| `user_id`         | string | The unique identifier of the user                                                                  |
| `traits`          | object | The traits associated with the user                                                                 |

**Example Request**

```json
POST /v1/users/identify HTTP/1.1
Host: api.raindrop.ai
Authorization: Bearer YOUR_WRITE_KEY
Content-Type: application/json

{
 "user_id": "user123",
 "traits": {
 "name": "John Doe",
 "email": "john@example.com",
 "age": 30,
 "plan": "paid" //we recommend 'free', 'paid', 'trial'
 }
}
```

**Response**

All authorized requests will return a `204 Success` status code. For debugging failures, contact us: [founders@raindrop.ai](mailto:founders@raindrop.ai).