# Clavis Endpoints: Events and SIMS Recommendations

Source: https://dev.arcxp.com/arc-intelligence/developer-docs/clavis-endpoints-events-and-sims-recommendations/

Once the Clavis v3 SDK has been installed, you can use two available endpoints:

1. **Events endpoint** is used to collect clickstream data from users
2. **SIMS Recommendations endpoint** uses event data to generate recommendations based on Popularity or Similarity

Notes:

- You can find the OpenAPI documentation in [Clavis V3 API](https://dev.arcxp.com/api/clavis/arc-xp-clavis-v3-api/)
- Clavis stores a `user.id` just to identify which user produces an event on which article. That `id` could be any string you want, you just have to ensure you identify each user uniquely. `user.id` is not related to cookies or sessions or any auth-related thing, so all users are always tracked as anonymous visitors by Clavis.
- To return Clavis recommendations, the **SIMS Recommendations endpoint requires at least 1000 events from 25 unique users who have each generated at least 2 events.**

## PutEvents Endpoint

Inserts events into Clavis to be considered on the algorithm for creating recommendations.

## Dates

All date-time objects are returned in UTC in the following ISO 8601 format:

`YYYY-MM-DDTHH:MM:SSZ`

## Parameters

The following parameters are required and must have a value:

- document.id
- document.site
- user.id
- click through (optional)

Example:

```js
  clavis
   .event({
      document: {
        id: '[DOCUMENT ID]',
        site: '[DOCUMENT SITE]',
      },
      user: {
        id: '[USER ID]',
      },
   })
   .then((response) => {
      console.log('Put event response: ${JSON.stringify(response, null, 2)}');
   });
```

## Response

Will output the confirmation of the event created and its unique id

```json
{
  "event": "e0ccf5af-ee15-460b-91c9-e71f1ed2f7b0",
  "status": "CREATED"
}
```

## SIMS Recommendations (Collaborative) Endpoint

## Recommendations Call

Usage: `recommendationsByDocument(document_id,n)`

## Parameters

The parameter `document_id` is the id of the article that will trigger the recommendations and `n` is the number of recommendations to retrieve. The value `n` is an optional parameter, if it’s not used, the default value will be **10**.

Example:

```js
clavis
  .recommendationsByDocument(
    '[DOCUMENT ID]',
    2, // Number of recommendations (optional, default 10)
  )
  .then((recommendations) => {
    console.log('Recommendations by document response: ${JSON.stringify(recommendations, null, 2)}');
  });
```

## Response

Will output the set of `document_id`’s with the following data already extracted from Content API:

- version
- created\_date
- last\_updated\_date
- publish\_date
- canonical\_url
- headlines
- website
- website\_url

```json
{
  "document_id": "[DOCUMENT ID]",
  "recommendations": [
    {
      "document_id": "[DOCUMENT ID]",
      "score": 1,
      "content": {
        "version": "0.10.6",
        "created_date": "2020-08-18T16:16:02.638Z",
        "last_updated_date": "2021-01-12T11:53:06.755Z",
        "publish_date": "2021-01-12T11:53:06.433Z",
        "canonical_url": "/example/url",
        "headlines": {
          "basic": "Example Text",
          "mobile": "",
          "native": "",
          "print": "",
          "tablet": "",
          "web": "",
          "meta_title": ""
        },
        "website": "[DOCUMENT SITE]",
        "website_url": "/example/url"
      }
    },
  ]
}
```

## Recommendation’s Error Responses

Codes: **2xxx**

Uses standard HTTP response codes to indicate success or failure. Codes in the `2xx` are successful, codes in the `4xx` range indicate that something is wrong with your request, and codes in the `5xx` indicate something went wrong with the API. All errors return an `error` field describing what went wrong.

```json
HTTP: 500
{
  "code": "2000",
  "error": "Recommendations Error: There is an unexpected error in recommendations engine. Try again later or contact support."
}

HTTP: 400
{
  "code": "2001",
  "error": "Invalid `items` parameter value"
}

HTTP: 500
{
  "code": "2002",
  "error": "No recommendations returned from Clavis"
}

HTTP: 404
{
  "code": "2101",
  "error": "Provided site (website parameter) not found"
}

HTTP: 500
{
  "code": "2102",
  "error": "Invalid content-api token"
}

HTTP: 500
{
  "code": "2103",
  "error": "Not documents found"
}

HTTP: 500
{
  "code": "2104",
  "error": "Unexpected missing property in returned payload"
}
```

We value your feedback! If you have suggestions, reach out to [Arc XP Customer Support](https://support.arcpublishing.com/) or post suggestions to [Our Ideas Portal](https://ideas.arcpublishing.com/).