API

Địa chỉ gốc: https://senaste.ai/api/v1. Mọi đường dẫn bên dưới đều đi kèm địa chỉ này. Hãy gửi header Authorization: Bearer uxp_.... Tạo một khóa trong tài khoản của bạn. Giới hạn là 60 yêu cầu mỗi phút; mỗi phản hồi đều có các header X-RateLimit-Limit, X-RateLimit-Remaining và X-RateLimit-Reset (giây còn lại đến hết phút hiện tại), và mã 429 sẽ có header Retry-After.

Toàn bộ API với cấu trúc của mọi phản hồi, dưới dạng OpenAPI 3.1 cho các bộ tạo mã và Postman: https://senaste.ai/api/v1/openapi.json

Từ trang web mới đến báo cáo

KEY=uxp_...
# 1. thêm trang web; phản hồi sẽ bao gồm id và "verification" (xác minh)
curl -X POST https://senaste.ai/api/v1/sites -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/pricing","task":"Find the price of the Pro plan","personas":["impulse","price"],"generate":2}'
# 2. đặt một bằng chứng lên trang web (DNS TXT, tệp hoặc thẻ meta), sau đó
curl -X POST https://senaste.ai/api/v1/sites/SITE_ID/verify -H "Authorization: Bearer $KEY"
# 3. tính giá cho lượt chạy mà chưa bắt đầu, rồi mới khởi động
curl -X POST https://senaste.ai/api/v1/runs -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"site":"SITE_ID","steps":20,"dry_run":true}'
curl -X POST https://senaste.ai/api/v1/runs -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: deploy-1234" \
  -d '{"site":"SITE_ID","steps":20,"concurrency":3,"callback_url":"https://example.com/hooks/senaste"}'
# 4. theo dõi tiến trình hoặc chờ callback
curl https://senaste.ai/api/v1/runs/RUN_ID -H "Authorization: Bearer $KEY"

Bỏ qua personas của một lần chạy để gửi tất cả những người được bật trên bảng điều khiển. Phản hồi cho POST /runs:

{"id":"rmhb2x1k4f9a0c3d1","site":"s1a2b3c4d5e6","domain":"example.com","status":"queued","personas":8,"steps":20,
 "credits":8,"refunded":0,"charged":8,"created":"2026-11-09T10:00:00.000Z","started":null,"finished":null,
 "queue":{"position":1,"ahead_yours":0,"ahead_others":0,"start_in_s":0,"done_in_s":190},
 "callback":{"url":"https://example.com/hooks/senaste","status":null},"warnings":[],"callback_secret":"..."}

Trong khi đang chạy, GET /runs/{id} sẽ trả về progress (tiến độ):

"progress":{"phase":"walking","percent":41,"personas_done":3,"personas_total":8,"steps_done":71,"steps_total":160,"eta_s":190,
 "personas":[{"persona":"p01","name":"Impulse buyer","step":20,"state":"done","outcome":"gave_up"},
             {"persona":"p02","name":"Price-first evaluator","step":7,"state":"walking"}]}

Khi một lượt chạy kết thúc: callback_url

Một lượt chạy được khởi động với callback_url (https, địa chỉ công khai) sẽ gửi một yêu cầu POST đến địa chỉ đó khi kết thúc: done (hoàn tất), failed (thất bại), cancelled (hủy) hoặc interrupted (bị gián đoạn). Thân yêu cầu là {"event":"run.finished","run":{...}} chứa trạng thái, điểm số và các số liệu; kết quả chi tiết có thể lấy từ GET /runs/{id}. Các header: X-Senaste-Event, X-Senaste-Timestamp (giây Unix) và X-Senaste-Signature: sha256=…, là chữ ký HMAC-SHA256 của timestamp + "." + body với khóa là callback_secret, khóa này chỉ hiển thị trong phản hồi của POST /runs. Hãy phản hồi với mã 2xx; nếu không, hệ thống sẽ thử lại sau 10 và 60 giây. Các chuyển hướng (redirects) sẽ không được tự động theo dõi.

// Node.js
const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(req.headers['x-senaste-timestamp'] + '.' + rawBody).digest('hex');
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(req.headers['x-senaste-signature']));

Phương thức

Phương thứcĐường dẫnNó làm gì
GET/balanceSố dư credits
GET/sitesTrang web của bạn, ID và panel
POST/sitesThêm một trang web: url, task (tối đa 500 ký tự), personas (các khóa thư viện từ GET /personas) và/hoặc generate (số lượng mô hình viết từ trang chủ, tối đa một phút), report_lang, audience. Phản hồi có verification: bản ghi DNS, tệp và thẻ meta, bất kỳ cái nào trong số đó chứng minh tên miền.
GET/sites/{id}Một trang web với panel của nó và, cho đến khi được xác minh, verification
POST/sites/{id}/verifyTìm kiếm bằng chứng ngay bây giờ. Trả về 200 kèm thông tin trang web khi tìm thấy (và referral nếu đây là lượt giới thiệu đã trả phí hoặc chưa nhận được bonus giới thiệu), 422 not_verified nếu chưa xác minh được.
GET/personasThư viện persona
GET/runsCác lần chạy của bạn, mới nhất trước, từng trang một: ?limit= từ 1 đến 100 (mặc định là 50). Khi next không null, hãy dùng nó với ?before= để lấy trang tiếp theo.
POST/runsBắt đầu một lượt chạy: steps từ 3 đến 30, concurrency từ 1 đến 4. Phản hồi có warnings: forms khi tác vụ yêu cầu gửi biểu mẫu, mua hoặc đăng ký (kiểm thử giữ lại biểu mẫu), offsite khi nó đề cập đến một tên miền khác. "dry_run":true chạy tất cả các kiểm tra và trả về 200 kèm credits, balance và would_start, không bắt đầu gì. Header Idempotency-Key giúp việc thử lại an toàn: cùng một key trong vòng 24 giờ sẽ trả về kết quả của lần chạy đã bắt đầu (200, Idempotent-Replayed: true). callback_url đã được mô tả ở trên.
GET/runs/{id}Trạng thái và kết quả theo từng persona. summary cho biết có bao nhiêu persona đã duyệt qua trang web và bao nhiêu lần kiểm tra bị lỗi; kết quả dạng này có failure kèm theo giai đoạn, bước và địa chỉ. Mỗi kết quả có steps (phần tử được sử dụng và effect, những gì trình duyệt đã làm) và goal_check: các phần của nhiệm vụ và liệu các màn hình có hiển thị từng phần hay không. Một persona cho biết đã đạt mục tiêu nhưng màn hình của nó chỉ hiển thị một phần nhiệm vụ sẽ có kết quả partly_reached. groups gộp các ghi chú từ nhiều persona về cùng một vấn đề; id của ghi chú có dạng persona:index. http liệt kê các lỗi HTTP kèm loại tài nguyên, liệu đó là tải trang, trang nào và bước nào. Một run trong hàng đợi có queue (vị trí, số run trước bạn và các tài khoản khác, giây đến khi bắt đầu và đến khi sẵn sàng); một run đang chạy có progress; một run hoàn tất có waited_s và ran_s. Bước nhập liệu có value là giá trị thực tế của trường sau khi nhập. notes_dropped liệt kê các ghi chú bị bỏ qua cùng lý do. Lỗi máy chủ trong http cũng có at (UTC), url, retry (thử lại sau 2 giây), hindered và các tiêu đề phản hồi để chủ trang web tra cứu trong nhật ký.
POST/runs/{id}/cancelHủy, số credits chưa dùng sẽ được hoàn lại

Lỗi

Định dạng: {"error":{"code":"...","message":"..."}}. Một giá trị ngoài phạm vi cũng sẽ hiển thị tên trường và các giới hạn của nó: {"error":{"code":"invalid_steps","message":"...","field":"steps","min":3,"max":30,"got":40}}

HTTPMãÝ nghĩa
400invalid_steps, invalid_concurrencySố bước hoặc độ đồng thời vượt quá giới hạn; không có gì được khởi động và không tiêu tốn tín dụng
400invalid_limit, invalid_cursorTrang của danh sách chạy được yêu cầu với limit hoặc before sai
400no_personasChưa chọn persona, hoặc id không tồn tại trên trang web này
400invalid_url, invalid_task, unknown_persona, invalid_generate, invalid_report_lang, domain_unreachableMột trang web mới có trường sai; không có gì được thêm vào
400invalid_dry_run, invalid_idempotency_key, invalid_callback_urlLỗi dry_run, Idempotency-Key hoặc callback_url; không có gì được khởi động
400not_test_hostChế độ thanh toán thử nghiệm cần một trang bắt đầu trên máy chủ thử nghiệm
401unauthorizedThiếu khóa hoặc khóa không hợp lệ
402insufficient_creditsKhông đủ credits
403domain_not_verifiedTên miền chưa được xác minh
404not_foundKhông có mục nào như vậy trong tài khoản của bạn
409too_many_runsQuá nhiều lần chạy trong hàng đợi
409site_exists, too_many_sitesTên miền đã có trong tài khoản của bạn, hoặc tài khoản đã có 20 trang web
422not_verifiedChưa tìm thấy bằng chứng về tên miền
502generation_failedMô hình không thể tạo persona; hãy thử lại hoặc chọn từ thư viện
429rate_limitedVượt quá giới hạn yêu cầu

Một lần chạy tác động thế nào lên trang web của bạn

Chỉ thực hiện các yêu cầu GET đến tên miền đã xác minh. Các biểu mẫu không được gửi và các trường mật khẩu, thẻ vẫn để trống, nên một lần chạy không bao giờ đăng ký, đăng nhập hoặc thanh toán. Ngoại lệ là chế độ thanh toán thử nghiệm, do bạn bật cho máy chủ thử nghiệm. Các ghi chú được tạo bởi mô hình, hãy kiểm tra chúng trước khi hành động.