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

# Segment Recommendations

> Get recommendations for a specific customer segment based on collective preferences.

## Authentication Required

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

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

## Path Parameters

<ParamField header="segment_id" type="string" required>
  Unique identifier for the customer segment to get recommendations for
</ParamField>

## Response

The API returns a JSON object with segment recommendations:

```json theme={null}
{
  "recommendation_id": "00000000-1234-5678-9abc-def012345678",
  "name": "Early Twenties",
  "segment_id": "cmcapwfrl01zk3m2t0axbh05e",
  "offers": [
    "00000000-aaca-4844-9cb0-54af8f897322",
    "00000001-c020-4d37-8d6e-4e4e30ff5671",
    "00000002-5fe2-466c-b58a-5ac8db631334"
  ],
  "type": "SEGMENT"
}
```

| Field               | Type   | Description                                            |
| ------------------- | ------ | ------------------------------------------------------ |
| `recommendation_id` | string | Unique identifier for the recommendation               |
| `name`              | string | Human-readable name for the segment                    |
| `segment_id`        | string | Identifier of the segment (matches the path parameter) |
| `offers`            | array  | Array of offer UUIDs that are recommended              |
| `type`              | string | Type of recommendation (SELF or SEGMENT)               |

## Error Codes

| Status Code | Description                               |
| ----------- | ----------------------------------------- |
| 200         | Recommendations retrieved successfully    |
| 400         | Invalid segment\_id format                |
| 401         | Unauthorized - Invalid or missing API key |
| 404         | Segment not found                         |
| 500         | Internal server error                     |

## Example

```bash theme={null}
curl -X GET https://api.hellocobi.com/v1/recommendations/segments/cmcapwfrl00zk3m2t0axba05e \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

## Best Practices

1. **Caching**: Cache segment recommendations as they change less frequently than individual customer recommendations
2. **Error Handling**: Implement proper error handling for cases where no recommendations are available
3. **Rate Limiting**: Be mindful of API rate limits (1000 requests per minute)
4. **Validation**: Validate the segment\_id format before making the request

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