> ## Documentation Index
> Fetch the complete documentation index at: https://docs.criar.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Activities

> School-wide event feed, achievement tracking, and parent engagement through reactions and comments.

## 1. API Purpose

The Activities API serves as the school's social feed. It communicates events, achievements, and general announcements to parents, fostering engagement through a familiar interactive interface.

***

## 2. Endpoint Definition

| Method | Route                          | Auth   | Description                         |
| ------ | ------------------------------ | ------ | ----------------------------------- |
| GET    | `/parent-app/activities`       | 🔐 JWT | View paginated activity feed        |
| GET    | `/teachers-app/activities`     | 🔐 JWT | List school-wide activities         |
| POST   | `/teachers-app/activities`     | 🔐 JWT | Post a new activity or announcement |
| PUT    | `/teachers-app/activities/:id` | 🔐 JWT | Edit existing activity details      |
| DELETE | `/teachers-app/activities/:id` | 🔐 JWT | Soft-delete an activity             |
| GET    | `/web-app/activities`          | 🔐 JWT | Admin: Comprehensive activity list  |

***

## 3. Authentication Flow

Standard Bearer JWT validation. Access is scoped by `skole_id`. Staff require specific RBAC permissions to create or delete posts.

***

## 4. Request Structure

#### GET /parent-app/activities

**Query Parameters:**

| Field          | Type   | Required | Description                          |
| -------------- | ------ | -------- | ------------------------------------ |
| activity\_type | string | No       | Filter by type (event/announcement). |
| student\_id    | string | No       | Filter by specific student.          |

#### GET /teachers-app/activities

**Query Parameters:**

| Field          | Type   | Required | Description                         |
| -------------- | ------ | -------- | ----------------------------------- |
| skole\_id      | string | Yes      | School identifier.                  |
| activity\_type | string | No       | Filter by type.                     |
| status         | string | No       | Filter by status (draft/published). |

#### POST /teachers-app/activities

**Request Body:**

```json theme={null}
{
  "skole_id": "SKL001",
  "title": "Annual Sports Day 2024",
  "description": "Join us for a day of sports and fun!",
  "activity_type": "event",
  "staff_id": 12,
  "student_id": null,
  "status": "published"
}
```

#### PUT /teachers-app/activities/:id

**Request Body:**

```json theme={null}
{
  "title": "Updated Title",
  "status": "cancelled"
}
```

#### DELETE /teachers-app/activities/:id

**URL Parameters:**

| Field | Type   | Description                   |
| ----- | ------ | ----------------------------- |
| id    | number | ID of the activity to delete. |

#### GET /web-app/activities

**Query Parameters:**

| Field     | Type   | Required | Description                     |
| --------- | ------ | -------- | ------------------------------- |
| skole\_id | string | Yes      | School identifier.              |
| page      | number | No       | Page number (Default: 1).       |
| limit     | number | No       | Records per page (Default: 10). |

***

## 5. Response Structure

#### Success: Parent Feed View (200 OK)

**Route:** `GET /parent-app/activities`

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": 88,
      "title": "Annual Sports Day",
      "activity_type": "event",
      "created_at": "2024-03-10T09:00:00Z"
    }
  ]
}
```

#### Success: Teacher Activity List (200 OK)

**Route:** `GET /teachers-app/activities`

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": 88,
      "title": "Sports Day",
      "status": "published",
      "author_id": 12
    }
  ]
}
```

#### Success: Activity Created (201 Created)

**Route:** `POST /teachers-app/activities`

```json theme={null}
{
  "success": true,
  "message": "Activity published successfully",
  "data": {
    "id": 89,
    "title": "New Announcement"
  }
}
```

#### Success: Activity Updated (200 OK)

**Route:** `PUT /teachers-app/activities/:id`

```json theme={null}
{
  "success": true,
  "message": "Update confirmed"
}
```

#### Success: Activity Deleted (200 OK)

**Route:** `DELETE /teachers-app/activities/:id`

```json theme={null}
{
  "success": true,
  "message": "Activity soft-deleted"
}
```

#### Success: Admin Dashboard Feed (200 OK)

**Route:** `GET /web-app/activities`

```json theme={null}
{
  "success": true,
  "data": {
    "records": [...],
    "pagination": { "total": 150, "page": 1 }
  }
}
```

***

## 6. Error Responses

| HTTP Code | Description                         |
| --------- | ----------------------------------- |
| 400       | Invalid `skole_id` or missing title |
| 404       | Activity not found                  |

***

## 7. Security Considerations

* **Soft Delete:** `deleted_status = 1` hides the item from all feeds without breaking database relations.
* **Tenant Isolation:** Enforced via `skole_id` in JWT payload.

***

## 8. Token Usage

```http theme={null}
GET /parent-app/activity?page=2
Authorization: Bearer <TOKEN>
```

***

## 9. Token Refresh

N/A.

***

## 10. Logout / Session Invalidation

N/A.

***

## 11. Usage Example (cURL)

```bash theme={null}
curl -H "Authorization: Bearer <TOKEN>" \
"http://localhost:3000/parent-app/activity?limit=5"
```

***

## 12. Notes / Special Behaviors

* **Engagement Integration:** Comments and reactions for activities are handled by the separate [Engagement API](/skole/api/13-engagement).
* **Targeting:** Activities can be "School-wide" or targeted to a specific `student_id`.