Ví dụ: tệp đính kèm

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ỏ.

1. Tải tệp lên

curl -sS -X POST "$ORIGIN/api/v1/attachments" \
  -H "Authorization: Bearer $AGENTFLOW_KEY" \
  -F "file=@hoa-don-1001.pdf;type=application/pdf"

201 Created:

{
  "id": "f2a8…",
  "original_filename": "hoa-don-1001.pdf",
  "content_type": "application/pdf",
  "byte_size": 184233,
  "uploaded_at": "2026-09-12T09:30:05.661802Z"
}

• Gửi đúng một phần multipart tên file. Thiếu phần đó, tệp rỗng hoặc multipart hỏng đều trả 400.
• Tệp vừa tải lên chưa gắn vào đâu, cho tới khi một biểu mẫu hay một công việc tham chiếu tới nó.

Tải lên với một khóa

export IDEMPOTENCY_KEY=$(uuidgen)

curl -sS -X POST "$ORIGIN/api/v1/attachments" \
  -H "Authorization: Bearer $AGENTFLOW_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -F "file=@hoa-don-1001.pdf;type=application/pdf"

• Gửi lại cùng tệp, cùng tên tệp và cùng kiểu nội dung với cùng khóa: 201 với cùng id, kèm header Idempotent-Replayed: true. Không có tệp thứ hai.
• Cùng khóa với một tệp khác, một tên tệp khác hoặc một kiểu nội dung khác: 422 IDEMPOTENCY_KEY_MISMATCH.
• Chi tiết nằm ở Thử lại an toàn.

2. Gắn tệp vào một hồ sơ

Đặt id vừa nhận vào trường tệp của biểu mẫu: một id, hoặc một mảng id khi trường nhận nhiều tệp. Ví dụ, tạo hồ sơ với trường hoa_don (một trường minh họa nhận nhiều tệp):

curl -sS -X POST "$ORIGIN/api/v1/entities/$ENTITY_ID/records" \
  -H "Authorization: Bearer $AGENTFLOW_KEY" \
  -H "Content-Type: application/json" \
  -d '{"form_payload": {"tieu_de": "PO-1001", "hoa_don": ["f2a8…"]}}'

Trường tệp của biểu mẫu khởi đầu nhận id theo cùng cách, trong input_payload khi khởi chạy một lượt chạy.

3. Đọc thông tin tệp

curl -sS "$ORIGIN/api/v1/attachments/$ATTACHMENT_ID" \
  -H "Authorization: Bearer $AGENTFLOW_KEY"

Phản hồi có cùng dạng với lúc tải lên, không kèm nội dung tệp. Tệp không tồn tại, hoặc thuộc tổ chức khác: 404.

4. Tải nội dung tệp

curl -sS -OJ "$ORIGIN/api/v1/attachments/$ATTACHMENT_ID/download" \
  -H "Authorization: Bearer $AGENTFLOW_KEY"

• Phản hồi là nội dung thô của tệp, với tên tệp trong header Content-Disposition (-OJ bảo curl lưu theo tên đó).
• Nội dung một tệp không bao giờ bị ghi đè, và phản hồi mang header ETag tính từ nội dung. Gửi lại giá trị đó trong If-None-Match thì nhận 304 Not Modified, không phải tải lại:

curl -sS -i "$ORIGIN/api/v1/attachments/$ATTACHMENT_ID/download" \
  -H "Authorization: Bearer $AGENTFLOW_KEY" \
  -H "If-None-Match: $ETAG"

HTTP/1.1 304 Not Modified

Tệp thuộc trường nhạy cảm

Một tệp đang được gắn vào một trường nhạy cảm chỉ trả thông tin và nội dung cho người gọi được xem trường đó, nhờ một hồ sơ bảo mật trường cấp quyền xem trường đó; tệp gắn vào nhiều trường nhạy cảm thì người gọi phải xem được tất cả các trường ấy. Một tệp từng được gắn vào một trường nhạy cảm nhưng nay không còn gắn vào trường nhạy cảm nào không trả cho người gọi thông thường nào. Người gọi nhận 403 ENTITY_ATTACHMENT_SENSITIVE, cả ở GET /api/v1/attachments/{attachment_id} lẫn ở …/download.