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

# HTTP API

> Here's how you can use the Raindrop API directly, without an SDK

### 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 theme={null}
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).

<Warning>
  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.
</Warning>

#### 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 theme={null}
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 theme={null}
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).