[LA-25015] Documentation for POST /v1/activities endpoint

source/includes/_activities.md

@@ -206,3 +206,194 @@ filters[verb] | "started" | Return activity for a specific verb. See [verbs](#ve
     ]
 }
 ```
+
+## Create an Activity
+
+##### NOTE: :construction: This endpoint is currently in beta and requires special access. Please raise a ticket on our [Customer Portal](https://learnamp.atlassian.net/servicedesk/customer/portal/1/user/login?destination=portal%2F1) to request access
+----
+
+Create an activty with a related [Item](#items) record and [Verb](#verbs). Please check to get an appropriate ID assigned to a specific verb.
+
+> Create a Activity record with an Item and Verb
+
+```shell
+curl --location 'hhttps://testaccount.learnamp.com/v1/activities' \
+--header 'Content-Type: application/json' \
+--header 'Authorization: Bearer a3DWMdP8mmFRtvulvanOGgII7U1dVV8LZ9zr6jyCq4k' \
+--header 'Cookie: _learnamp_session_=aadc48937fec7520fd7cf3f7e55681e4' \
+--form 'user_id="1"' \
+--form 'verb_id="54"' \
+--form 'item_id="10"'
+```
+
+```ruby
+module Learnamp
+  class Activities
+    include HTTParty
+    base_uri "#{ENV['BASE_URL']}#{ENV['API_PATH']}"
+
+    attr_accessor :token
+
+    def initialize(token)
+      @token = token
+    end
+
+    def create(params)
+      response = self.class.post("/activities", { body: params, headers: headers })
+      response.parsed_response
+    end
+
+    private
+
+    def headers
+      {
+        'Authorization' => "Bearer #{token}"
+      }
+    end
+  end
+end
+
+params_with_item_id = {
+    user_id: '1',
+    verb_id: '54'
+    item_id: '10',
+}
+
+item_activity = Learnamp::Activities.new(token).create(params_with_item_id)
+
+params_with_external_id_item = {
+    user_id: '1',
+    verb_id: '54'
+    external_id: 'content_1234567890abcdef',
+}
+
+external_item_activity = Learnamp::Activities.new(token).create(params_with_external_id_item)
+
+params_with_slug = {
+    user_id: '1',
+    verb_id: '54'
+    slug: 'content-slug-for-activity',
+}
+
+activity = Learnamp::Activities.new(token).create(params_with_slug)
+```
+
+### Data in Body
+
+**Note:** The following parameters are mutually exclusive. It means you can only use one of other parameters to be a valid request.
+- For the User the Activity belongs to:
+  - `user_id`
+  - `email`
+- For the Item the Activity belongs to:
+  - `slug`
+  - `item_id`
+  - `external_id`
+
+Parameter | Example value | Description (* required)
+--------- | ------- | -----------
+user_id | 1 | ID of the User. 
+email | testuser@test.com | Email address of user.
+verb_id | 54 | ID of the [Verb](#verbs) for this activity. *(\*)*
+item_id | 1 | ID of the Item that is created within the Learn Amp platform.
+slug | 'content-slug-for-activity' | Slug of an existing Item in the platform. 
+external_id | 1 or 'content_1234567890abcdef' | `source_id` of the Item that is in the Learn Amp platform but was created through the [Items](#items) create endpoint.
+
+> 201 Created - succesful response:
+
+```json
+{
+    "id": 225,
+    "activityable": {
+        "id": 10,
+        "name": "Content",
+        "shortDescription": null,
+        "type": "Item",
+        "url": "hhttps://testaccount.learnamp.com/en/items/content-slug-for-activity",
+        "addedBy": {
+            "id": 1,
+            "firstName": "First Name",
+            "lastName": "Last Name",
+            "jobTitle": "CTO",
+            "email": "firstlast.lastname@learnamp.com",
+            "timeZone": "London",
+            "language": "en",
+            "role": "viewer",
+            "hireDate": null,
+            "profileUrl": "hhttps://testaccount.learnamp.com/en/users/1",
+            "status": {
+                "status": "Confirmed",
+                "time": "On 4 Apr 23"
+            }
+        },
+        "displayAddedBy": false,
+        "totalTimeEstimate": "< 5 mins"
+    },
+    "user": {
+        "id": 1,
+        "firstName": "First Name",
+        "lastName": "Last Name",
+        "jobTitle": "Last Name",
+        "email": "firstlast.lastname@learnamp.com",
+        "timeZone": "London",
+        "language": "en",
+        "role": "viewer",
+        "hireDate": null,
+        "profileUrl": "hhttps://testaccount.learnamp.com/en/users/1",
+        "status": {
+            "status": "Confirmed",
+            "time": "On 4 Apr 23"
+        }
+    },
+    "verb": "started",
+    "createdAt": "2025-02-17T16:08:29Z",
+    "expiredAt": null,
+    "result": "",
+    "completed": false,
+    "expired": false,
+    "score": null,
+    "totalTime": null
+}
+```
+
+> 400 Bad Request - validation errors:
+
+```json
+{
+    "error": "email is invalid, user_id, email are mutually exclusive",
+    "fullErrors": {
+        "email": [
+            "is invalid"
+        ],
+        "userId": [
+            "are mutually exclusive"
+        ]
+    }
+}
+```
+```json
+{
+    "error": "item_id, external_id are mutually exclusive",
+    "fullErrors": {
+        "itemId": [
+            "are mutually exclusive"
+        ]
+    }
+}
+```
+```json
+{
+    "error": "item_id, slug are mutually exclusive",
+    "fullErrors": {
+        "itemId": [
+            "are mutually exclusive"
+        ]
+    }
+}
+```
+
+> 404 Not Found - unsuccessful response:
+
+```json
+{
+    "error": "Couldn't find Verb with 'id'=666"
+}