> ## 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.

# Overview

> The Cobi Recommendations API provides personalized recommendations for customers and segments based on their preferences and behavior.

<Note>
  The Cobi Recommendations API delivers personalized recommendations to enhance
  user engagement and improve conversion rates.
</Note>

## API Structure

All Recommendations API endpoints follow the same URL pattern:

<CodeGroup>
  ```http URL Pattern theme={null}
  GET /v1/recommendations/:type/:id
  ```

  ```http Customers Example theme={null}
  GET /v1/recommendations/customers/{customer_id}
  ```

  ```http Segments Example theme={null}
  GET /v1/recommendations/segments/{segment_id}
  ```
</CodeGroup>

Where `:type` is one of:

<Steps>
  <Step title="Customers">
    Get personalized recommendations for a specific customer
  </Step>

  <Step title="Segments">
    Get recommendations for a specific customer segment
  </Step>
</Steps>

## Common Features

<AccordionGroup>
  <Accordion title="Authentication">
    All endpoints require API key authentication via the Authorization header:

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

    <Tip>
      Contact our support team to obtain your API key.
    </Tip>
  </Accordion>

  <Accordion title="Response Format">
    All endpoints return a consistent response format:

    ```json theme={null}
    [
      {
        "name": "string",
        "student_id": "string (UUID)",
        "offers": ["string (UUID)"]
      }
    ]
    ```

    The response is an array of recommendation objects, each containing:

    * `name`: Human-readable name for the recommendation set
    * `student_id` or `segment_id`: Identifier for the customer or segment
    * `offers`: Array of offer UUIDs that are recommended
  </Accordion>

  <Accordion title="Rate Limiting">
    Recommendations are computationally intensive. Please be mindful of rate limits:

    * Maximum 1000 requests per minute per API key
    * Consider caching recommendations for frequently requested customers/segments
  </Accordion>
</AccordionGroup>

## Available Endpoints

<CardGroup cols={2}>
  <Card title="Customer Recommendations" icon="user" href="/api-reference/recommendations/endpoint/customers" color="#4CAF50">
    Get personalized recommendations for a specific customer based on their
    preferences and behavior
  </Card>

  <Card title="Segment Recommendations" icon="users" href="/api-reference/recommendations/endpoint/segments" color="#2196F3">
    Get recommendations for a specific customer segment based on collective
    preferences
  </Card>
</CardGroup>

## Best Practices

<Tabs>
  <Tab title="Performance">
    * Cache recommendations for frequently requested customers/segments -
      Implement proper error handling for failed requests - Use appropriate
      timeouts for recommendation requests
  </Tab>

  <Tab title="Data Quality">
    * Ensure customer\_id and segment\_id are valid UUIDs - Handle cases where no
      recommendations are available - Validate offer IDs returned in
      recommendations
  </Tab>

  <Tab title="Security">
    * Store your API key securely - Rotate API keys periodically - Use HTTPS for
      all API requests
  </Tab>
</Tabs>

Need help? Contact our support team at [support@hellocobi.com](mailto:support@hellocobi.com)