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 (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
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.
Event has a limit of 1 MB. Properties will be truncated for larger events. Contact us 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
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.
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
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.