> ## Documentation Index
> Fetch the complete documentation index at: https://client-integrations-api-dev.sequen.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Integrate Sequen using direct API calls to upload data, send events, and get recommendations.

Welcome to the Sequen quickstart guide! This guide shows you how to interact directly with the Sequen API to upload your item catalog, send user engagement events, and retrieve personalized recommendations.

## Prerequisites

* An active Sequen account. If you don't have one, [request an audit](https://sequen.ai/request-audit), or speak with your account representative to get started.
* Your Sequen API Key (found in your Sequen dashboard, or provided by our development team). You'll use this in the `Authorization` header for your API requests (e.g., `Authorization: Bearer YOUR_SEQUEN_API_KEY`).
* A tool for making HTTP requests, like `curl` or Postman. The examples below use `curl`.

## Integration Steps

<Steps>
  ### Step 1: Upload Your Item Catalog

  To provide recommendations, Sequen needs to know about the items in your catalog. You can upload or update items in your catalog using the `/catalog/item` endpoint.

  Here's an example of how to create or update an item:

  ```bash Upload Item via API theme={null}
  curl -X PUT 'https://api.sequen.com/v1/catalog/item' \
  -H 'Authorization: Bearer YOUR_SEQUEN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "item_id": "ST678VG",
    "title": "Itelios workshop desk - Premium",
    "status": "active",
    "description": "Solid wood workshop desk with reinforced frame for heavy tools.",
    "price": "1099.99",
    "price_currency": "USD",
    "metadata": [
      { "key": "material", "value": "solid oak", "type": "text" },
      { "key": "dimensions", "value": "120x80x75cm", "type": "text" },
      { "key": "weight", "value": "50", "type": "number" },
      { "key": "load_capacity", "value": "150", "type": "number" }
    ]
  }'
  ```

  Refer to the [Update Item API Reference](/api-reference/endpoint/create) for more details on the request and response structure. It's recommended to upload your entire catalog initially and then send updates as items change.

  ### Step 2: Send User Engagement Events

  Sequen learns from user interactions (engagement events) to personalize recommendations and improve model performance. Send events using the `/cds/engagement` endpoint.

  Events should include relevant context like user identifiers, session identifiers, and details about the item or page being interacted with. The endpoint accepts both single events and batches of events for bulk uploads.

  Here's an example of sending a single `add_to_cart` event:

  ```bash Send Engagement Event via API theme={null}
  curl -X POST 'https://api.sequen.com/v1/cds/engagement' \
  -H 'Authorization: Bearer YOUR_SEQUEN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "add_to_cart",
    "userId": "user_f9b3d",
    "sessionId": "session_k2p0a",
    "timestamp": "2024-07-27T10:30:00Z",
    "properties": {
      "item_id": "SKU-12345-BLK-L",
      "page_type": "product_detail",
      "quantity": 1,
      "price": 59.99,
      "currency": "USD",
      "category_path": "Apparel > Tops > T-Shirts",
      "color": "Black",
      "size": "L"
    }
  }'
  ```

  Common event types include `view`, `click`, `purchase`, `add_to_cart`, and `search`. Refer to the [CDS Engagement Events API Reference](/api-reference/cds-engagement) for detailed information on sending single or multiple events.

  ### Step 3: Query Recommendations

  Once you have uploaded items and are sending engagement data, you can retrieve personalized recommendations using the `/recommend` endpoint.

  You can request recommendations based on a `user_id`, `session_id`, `item_id` (for similar items), a list of `item_ids`, or recent `events`.

  Here's an example request for recommendations for a user, based on items they've interacted with and some recent events:

  ```bash Get Recommendations via API theme={null}
  curl -X POST 'https://api.sequen.com/v1/recommend' \
  -H 'Authorization: Bearer YOUR_SEQUEN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "user_id": "2f396d29fb98",
    "item_ids": ["ST678VG", "QW1234"],
    "events": [
      {
        "timestamp": "2024-06-14T10:00:00Z",
        "type": "browse",
        "item_id": "ST678VG",
        "description": "Viewed workshop desk details page"
      }
    ],
    "limit": 10,
    "model_name": "furniture_v2"
  }'
  ```

  The response will contain a list of recommended item IDs, optionally with scores. See the [Recommendations API Reference](/api-reference/recommendations) for all available parameters.

  ### Step 4: Explore Further

  You've now seen the basics of interacting with the Sequen API!

  * Dive deeper into the [API Reference](/api-reference) for detailed endpoint information, including other useful endpoints like [Search](/api-reference/search).
  * Configure your optimization goals and monitor performance in the Sequen RUMI Dashboard.
</Steps>

Need help? Contact us at [hello@sequen.ai](mailto:hello@sequen.ai).