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

# Notifications API — Fetch, Read & Delete Alerts

> REST API endpoints for retrieving, marking as read, and deleting user notifications including project updates, investments, and platform alerts.

The Notifications API lets you retrieve, mark as read, and delete the in-app notifications generated by the EarthCoop platform. Notifications are produced automatically when key events occur — such as a project's approval status changing, an admin requesting project revisions, or a new investment being received. All notification endpoints require a valid Bearer token.

***

## Notification Types

The platform currently generates four types of notifications.

### `project_status_changed`

Sent to a project owner when the status of their project changes (approved, rejected, under review, archived).

**Notification `data` fields:**

<ResponseField name="data.type" type="string">
  Always `project_status_changed`.
</ResponseField>

<ResponseField name="data.project_id" type="integer">
  ID of the affected project.
</ResponseField>

<ResponseField name="data.project_title" type="string">
  Title of the affected project.
</ResponseField>

<ResponseField name="data.status" type="string">
  New project status: `approved`, `rejected`, `under_review`, or `archived`.
</ResponseField>

<ResponseField name="data.message" type="string">
  Human-readable status change message.
</ResponseField>

<ResponseField name="data.comment" type="string">
  Optional reviewer comment, or `null`.
</ResponseField>

<ResponseField name="data.url" type="string">
  Deep link to the project page.
</ResponseField>

***

### `project_revision_requested`

Sent to a project owner when an administrator requests changes to their project before it can be approved.

**Notification `data` fields:**

<ResponseField name="data.type" type="string">
  Always `project_revision_requested`.
</ResponseField>

<ResponseField name="data.project_id" type="integer">
  ID of the project requiring revision.
</ResponseField>

<ResponseField name="data.project_title" type="string">
  Title of the project.
</ResponseField>

<ResponseField name="data.message" type="string">
  Standard notification message.
</ResponseField>

<ResponseField name="data.revision_notes" type="string">
  Specific revision instructions from the administrator.
</ResponseField>

<ResponseField name="data.url" type="string">
  Deep link to the project edit page.
</ResponseField>

***

### `new_investment_received`

Sent to a project owner when an investor completes a payment for one of their projects.

**Notification `data` fields:**

<ResponseField name="data.type" type="string">
  Always `new_investment_received`.
</ResponseField>

<ResponseField name="data.investment_id" type="integer">
  ID of the new investment record.
</ResponseField>

<ResponseField name="data.project_id" type="integer">
  ID of the project receiving investment.
</ResponseField>

<ResponseField name="data.project_title" type="string">
  Title of the project.
</ResponseField>

<ResponseField name="data.amount" type="integer">
  Investment amount in the platform's currency unit (گل).
</ResponseField>

<ResponseField name="data.investor_name" type="string">
  Display name of the investor.
</ResponseField>

<ResponseField name="data.message" type="string">
  Notification message text.
</ResponseField>

<ResponseField name="data.url" type="string">
  Deep link to the project's investment overview.
</ResponseField>

***

### `investment_status_changed`

Sent to an investor when the status of their investment changes (paid, active, completed, cancelled, refunded).

**Notification `data` fields:**

<ResponseField name="data.type" type="string">
  Always `investment_status_changed`.
</ResponseField>

<ResponseField name="data.investment_id" type="integer">
  ID of the investment.
</ResponseField>

<ResponseField name="data.project_title" type="string">
  Title of the associated project.
</ResponseField>

<ResponseField name="data.amount" type="integer">
  Investment amount in the platform's currency unit (گل).
</ResponseField>

<ResponseField name="data.status" type="string">
  New investment status: `paid`, `active`, `completed`, `cancelled`, or `refunded`.
</ResponseField>

<ResponseField name="data.message" type="string">
  Human-readable status change message.
</ResponseField>

<ResponseField name="data.notes" type="string">
  Optional additional notes (e.g. refund amount), or `null`.
</ResponseField>

<ResponseField name="data.url" type="string">
  Deep link to the investment detail page.
</ResponseField>

***

## Notification Object Structure

Every notification returned by the API shares the following top-level shape:

<ResponseField name="id" type="string">
  UUID of the notification record.
</ResponseField>

<ResponseField name="type" type="string">
  A string identifying the notification category, such as `project_status_changed` or `new_investment_received`.
</ResponseField>

<ResponseField name="data" type="object">
  The notification payload. The structure varies by notification type — see the type-specific fields above.
</ResponseField>

<ResponseField name="read_at" type="string|null">
  ISO 8601 timestamp of when the notification was marked as read, or `null` if unread.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp of when the notification was created.
</ResponseField>

***

## GET /api/notifications

Returns the authenticated user's unread notifications, ordered newest first.

**Authentication:** Required — `Authorization: Bearer {token}`

**Request:** No parameters.

### Example Request

```bash theme={null}
curl -X GET https://your-domain.com/api/notifications \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"
```

### Example Response

```json theme={null}
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "project_status_changed",
    "data": {
      "type": "project_status_changed",
      "project_id": 123,
      "project_title": "Community Solar Farm Initiative",
      "status": "approved",
      "message": "Your project has been approved and is ready to receive investments.",
      "comment": null,
      "url": "https://your-domain.com/projects/123"
    },
    "read_at": null,
    "created_at": "2024-11-15T10:30:00Z"
  },
  {
    "id": "660f9511-f30c-52e5-b827-557766551111",
    "type": "new_investment_received",
    "data": {
      "type": "new_investment_received",
      "investment_id": 456,
      "project_id": 123,
      "project_title": "Community Solar Farm Initiative",
      "amount": 10000000,
      "investor_name": "Reza Karimi",
      "message": "A new investment has been recorded for your project.",
      "url": "https://your-domain.com/projects/123"
    },
    "read_at": null,
    "created_at": "2024-11-15T11:00:00Z"
  }
]
```

### Error Responses

**Unauthenticated — 401:**

```json theme={null}
{
  "message": "Unauthenticated."
}
```

***

## POST /api/notifications/{id}

Marks a specific notification as read by setting its `read_at` timestamp to the current time.

**Authentication:** Required — `Authorization: Bearer {token}`

### Path Parameters

<ParamField path="id" type="string" required>
  The UUID of the notification to mark as read.
</ParamField>

**Request body:** None required.

### Example Request

```bash theme={null}
curl -X POST https://your-domain.com/api/notifications/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"
```

### Example Response

```json theme={null}
{
  "success": true,
  "message": "Notification marked as read."
}
```

### Error Responses

**Notification not found — 404:**

```json theme={null}
{
  "message": "Not found."
}
```

***

## DELETE /api/notifications/{id}

Permanently deletes a notification from the authenticated user's notification list.

**Authentication:** Required — `Authorization: Bearer {token}`

### Path Parameters

<ParamField path="id" type="string" required>
  The UUID of the notification to delete.
</ParamField>

**Request body:** None required.

### Example Request

```bash theme={null}
curl -X DELETE https://your-domain.com/api/notifications/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"
```

### Example Response

```json theme={null}
{
  "success": true,
  "message": "Notification deleted."
}
```

<Note>
  Deleting a notification is permanent and cannot be undone. If you want to keep a record of the notification, mark it as read instead.
</Note>

### Error Responses

**Notification not found — 404:**

```json theme={null}
{
  "message": "Not found."
}
```

**Unauthenticated — 401:**

```json theme={null}
{
  "message": "Unauthenticated."
}
```