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

# Interactions

> Record and retrieve user interactions with items (TAG, OFFER, SHOP, KEYWORD).

<Note>
  **Important**: User interaction records have dependencies on students. The
  system validates the `student_id` against existing records in the database.
  You should upload student data before uploading user interaction records to
  ensure proper data validation. The `item_id` field must reference the correct
  item type as specified by `item_type`.
</Note>

## Authentication Required

This endpoint may require API key authentication via Bearer token in the Authorization header.

```http theme={null}
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## About the Endpoint

This endpoint allows you to record and retrieve user interactions with items (TAG, OFFER, SHOP, KEYWORD).

### Source Field for Recommendation Feedback

The `source` field is crucial for tracking recommendation API effectiveness:

* **`null`**: Normal user browsing interactions (not from recommendations)
* **`"COBI"`**: Interactions that originated from recommendation API responses

This enables the recommendation system to:

* Track which recommendations led to user engagement
* Measure recommendation algorithm effectiveness
* Improve future recommendations based on user behavior patterns

## Request Body

<ParamField body="interaction_type" type="string" required>
  Type of interaction. One of: FILTER\_CLICK, SHARE, PAGE\_VIEW, DISCOUNT\_CODE
</ParamField>

<ParamField body="user_id" type="string">
  Psuedo ID of the user
</ParamField>

<ParamField body="student_id" type="string (UUID)">
  UUID of the student
</ParamField>

<ParamField body="item_type" type="string" required>
  One of: TAG, OFFER, SHOP
</ParamField>

<ParamField body="item_id" type="string (UUID)" required>
  UUID of the item (TAG, OFFER, KEYWORD, or SHOP) as determined by `item_type`
</ParamField>

<ParamField body="city" type="string">
  City where the interaction occurred
</ParamField>

<ParamField body="country" type="string">
  Country where the interaction occurred
</ParamField>

<ParamField body="platform" type="string">
  One of: ANDROID, IOS, WEB, OTHER
</ParamField>

<ParamField body="event_timestamp" type="int or ISO string" required>
  Event timestamp (positive integer or ISO datetime string)
</ParamField>

<ParamField body="source" type="string">
  Source of interaction. Set to 'COBI' when from recommendation API, null
  otherwise
</ParamField>

<ParamField body="recommendation_id" type="string (UUID)">
  Recommendation ID of cobi recommended interaction, null otherwise
</ParamField>

## Response

The API returns a JSON response with the created interaction object on success.

* `201 Created` on success
* `400 Bad Request` if validation fails

## Error Codes

| Status Code | Description                      |
| ----------- | -------------------------------- |
| 201         | Interaction created successfully |
| 400         | Validation error                 |
| 401         | Unauthorized - Invalid API key   |
| 500         | Internal server error            |

## Example

```bash theme={null}
curl -X POST https://api.hellocobi.com/user-interactions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "interaction_type": "FILTER_CLICK",
    "user_id": "75962b04e5caa7e582e2bc2949587ed9",
    "student_id": "b1a2c3d4-e5f6-7890-abcd-1234567890ef",
    "item_type": "TAG",
    "item_id": "a1b2c3d4-e5f6-7890-abcd-1234567890ab",
    "city": "Berlin",
    "country": "Germany",
    "platform": "WEB",
    "event_timestamp": 1718035200,
    "source": "COBI",
    "recommendation_id": "6fc7eb1d-a516-4a9b-8dcc-313976461ae4"
  }'
```