Ví dụ: thông báo

Thông báo thuộc về một người. Cả bốn thao tác dưới đây đều là x-person-only: chủ thể dịch vụ gọi sẽ nhận 403 USER_IDENTITY_REQUIRED, vì chủ thể dịch vụ không bao giờ nhận thông báo. Hiện cũng chưa có cách để một ứng dụng bên thứ ba đăng nhập người dùng rồi gọi thay họ — xem Xác thực.

Các yêu cầu dưới đây là những gì ứng dụng AgentFlow gửi cho người đang đăng nhập, bằng cookie phiên của họ. Chúng được đưa ra để bạn thấy hình dạng của yêu cầu và phản hồi. Phản hồi đã được rút gọn; … đánh dấu phần lược bỏ.

1. Danh sách thông báo

curl -sS -G "$ORIGIN/api/v1/notifications" \
  -b "session=$SESSION" \
  --data-urlencode "unread=true" \
  --data-urlencode "limit=20"

{
  "items": [
    {
      "id": "8b3c…",
      "event_kind": "work_assigned",
      "params": { "record_id": "5b90…", "entity_id": "e41c…", … },
      "action_url": "/inbox?record=5b90…&entity=e41c…",
      "instance_id": "c04b…",
      "is_read": false,
      "read_at": null,
      "created_at": "2026-09-12T08:15:03.004512Z"
    }
  ],
  "next_cursor": null,
  "prev_cursor": null
}

• Thông báo mới nhất đứng trước: sort là created_at, và dir mặc định là desc. unread=true chỉ lấy thông báo chưa đọc.
• q khớp phần đầu của event_kind, đúng như viết: q=work_ lấy các thông báo công việc (work_assigned, work_digest và các loại work_* còn lại); workflow_task_completed bắt đầu khác nên hãy hỏi nó bằng q=workflow_.
• Thông báo về công việc gọi tên bản ghi của nó, không phải task: params mang record_id và entity_id (và, với một bước quy trình, tên quy trình và tên bước) còn action_url mở bản ghi trong hộp thư. Không còn task_id. params không bao giờ mang tiêu đề của bản ghi, vì chúng chỉ chứa nhãn lúc thiết kế và tên do hệ thống tạo.
• Thông báo không mang sẵn câu chữ: tiêu đề và nội dung được dựng từ event_kind và params, theo ngôn ngữ của người đọc. Hãy chịu được một event_kind bạn chưa gặp.
• Trang kế tiếp: thêm cursor là giá trị next_cursor. Quay lại trang trước: gửi prev_cursor làm before. Xem Phân trang.

2. Số thông báo chưa đọc

curl -sS "$ORIGIN/api/v1/notifications/unread-count" \
  -b "session=$SESSION"

{ "unread": 3, "latest_id": "8b3c…", "latest_at": "2026-09-12T08:15:03.004512Z" }

latest_id và latest_at chỉ thông báo mới nhất — một cách rẻ để biết có gì mới mà không cần tải lại cả danh sách.

3. Đánh dấu đã đọc

Một thông báo:

curl -sS -X POST "$ORIGIN/api/v1/notifications/$NOTIFICATION_ID/read" \
  -b "session=$SESSION"

Tất cả:

curl -sS -X POST "$ORIGIN/api/v1/notifications/read-all" \
  -b "session=$SESSION"

Cả hai trả 204 No Content.

4. Chủ thể dịch vụ gọi thì sao

curl -sS -i "$ORIGIN/api/v1/notifications" \
  -H "Authorization: Bearer $AGENTFLOW_KEY"

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json

{ "type": "USER_IDENTITY_REQUIRED", "status": 403, "request_id": "…", … }