Ví dụ: bảng điều khiển

Các lệnh dưới đây gọi API với tư cách một chủ thể dịch vụ:

export ORIGIN=https://agentflow.example.com
export AGENTFLOW_KEY=afk_…

Phản hồi đã được rút gọn; … đánh dấu phần lược bỏ.

Một chủ thể dịch vụ mở được bảng điều khiển chia sẻ với cả tổ chức, bảng chia sẻ với một nhóm mà nó thuộc về, hoặc mọi bảng khi có dashboard.manage.any. Mọi con số được tính trong phạm vi của chính người gọi: hai người gọi có quyền khác nhau có thể thấy hai con số khác nhau trên cùng một ô.

1. Liệt kê bảng điều khiển

curl -sS -G "$ORIGIN/api/v1/dashboards" \
  -H "Authorization: Bearer $AGENTFLOW_KEY" \
  --data-urlencode "scope=organization" \
  --data-urlencode "limit=20"

{
  "items": [
    {
      "id": "b40e…",
      "name": "Mua sắm theo quý",
      "description": null,
      "visibility": "organization",
      "owner_display_name": "Nguyễn Thị Lan",
      "entity_ids": ["0a5f…"],
      "unavailable_tile_count": 0,
      "updated_at": "2026-09-10T04:18:52.330915Z",
      …
    }
  ],
  "next_cursor": null,
  "prev_cursor": null
}

• scope là mine, all, shared, organization hoặc pinned. Không gửi thì một người nhận mine, còn chủ thể dịch vụ — vốn không sở hữu bảng nào — nhận all. Một giá trị khác trả 400 INVALID_QUERY_PARAMETER.
• q tìm theo một phần của tên hoặc mô tả của bảng, tên hoặc email của người sở hữu, hoặc tên thực thể mà một ô nói về, không phân biệt hoa thường.
• sort là updated_at, dir là asc hoặc desc; không gửi thì bảng mới sửa đứng trước.
• unavailable_tile_count đếm số ô mà chính người gọi không xem được.

2. Mở một bảng

curl -sS "$ORIGIN/api/v1/dashboards/$DASHBOARD_ID" \
  -H "Authorization: Bearer $AGENTFLOW_KEY"

{
  "id": "b40e…",
  "name": "Mua sắm theo quý",
  "visibility": "organization",
  "tiles": [ … ],
  "filter_bar": {
    "controls": [
      { "id": "6f1d…", "label": "Kỳ", "kind": "date_period", … }
    ],
    "defaults": { "6f1d…": "this_quarter" }
  },
  "updated_at": "2026-09-10T04:18:52.330915Z",
  …
}

• Bảng không tồn tại, hoặc người gọi không được mở: 404.
• tiles là đặc tả của bảng, không chứa con số nào. Con số đến từ bước tính ở dưới.
• filter_bar.controls là các bộ lọc của trang. kind là date_period, enum, reference, text, number hoặc boolean. defaults là giá trị mặc định đã lưu, theo id của bộ lọc.

3. Tính các ô

curl -sS -X POST "$ORIGIN/api/v1/dashboards/$DASHBOARD_ID/compute" \
  -H "Authorization: Bearer $AGENTFLOW_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filter_values": {"6f1d…": "last_30_days"}}'

{
  "tiles": [
    {
      "tile_id": "1a90…",
      "outcome": "ok",
      "measures": { "…": { "value": 1204.0, "population": 1204, … } },
      "coverage": { "partial": false },
      "population": { "count": 1204, "capped": false, "cap": 20000, "membership_rule": "lowest_record_id" },
      "computed_at": "2026-09-12T10:02:17.448120Z"
    },
    {
      "tile_id": "7c22…",
      "outcome": "unavailable",
      "problem": { "type": "TILE_ENTITY_UNAVAILABLE", "title": "Not available to you", "status": 404 },
      "coverage": { … },
      "computed_at": "2026-09-12T10:02:17.448120Z"
    }
  ]
}

• Thân yêu cầu không bắt buộc. filter_values là giá trị của riêng lần gọi này cho các bộ lọc của trang, theo id. Chúng được áp lên defaults và không ghi lại gì. Gửi null cho một bộ lọc là bỏ bộ lọc đó.
• Bộ lọc date_period nhận tên một khoảng thời gian — ví dụ this_quarter, last_30_days — hoặc một khoảng {from, to}.
• outcome là ok, unavailable hoặc failed. unavailable nghĩa là người gọi không được xem thực thể của ô, và ô không tiết lộ con số nào. failed nghĩa là ô không tính được; problem.type và problem.detail nêu lý do. Một ô không tính được không làm hỏng các ô còn lại.
• Mỗi mục trong measures có value và population. value là null khi không xác định được — không bao giờ bị thay bằng 0.
• population.capped: true nghĩa là số hồ sơ vượt ngưỡng cap; các con số khi đó chỉ tính trên phần hồ sơ mà membership_rule chọn.
• coverage.unfiltered_by_dashboard_filter nghĩa là thực thể của ô không áp được một bộ lọc của trang; coverage.declined_dashboard_filter nghĩa là ô cố ý không áp nó.
• Một ô danh sách không trả về hàng. Nó trả list gồm entity_id, view_id và filter; lấy hàng bằng POST /api/v1/entities/{entity_id}/records/query, như trong ví dụ về hồ sơ.