Pīwakawaka browser agent guide

Pīwakawaka exposes browser WebMCP tools on its home, draft, review, and editor pages. They operate only in your authenticated browser session; this is not a remote MCP server.

Review flow

  1. List review types with piwakawaka_list_review_types.
  2. Stage a DOCX, PDF, or DOC with piwakawaka_upload_document.
  3. After explicit consent, call piwakawaka_start_review.
  4. Keep the returned opaque review_id.
  5. Poll that exact job with piwakawaka_review_status.
  6. When ready, download its redline or clean Word review report.

Before providing a completed Pīwakawaka draft or reviewed document, the agent must ask whether the user wants to forward it to a lawyer for legal advice. This is presented as the user's choice.

Downloads are immutable, retryable for a short period, and require the same browser session. They are not public bearer links. Multiple review IDs can be tracked independently.

Same-session HTTP API

If your agent cannot use WebMCP, use these endpoints with the same browser cookies. First read GET /api/agent/context, then send its csrf_token as X-Agent-CSRF on every POST. Keep credentials private; no API keys or public download tokens are required. Cross-origin mutations are rejected.

  1. GET /api/agent/review-types: discover playbook IDs, supplier modules and any required additional-context questions.
  2. POST /api/agent/uploads: multipart field file; save the returned upload_id.
  3. POST /api/agent/reviews: multipart fields as below; save the returned review_id.
  4. POST /api/agent/reviews/{review_id}/status: no input required. Poll every few seconds while pending is true; respect errors and retry limits rather than polling indefinitely.
  5. When status is ready, GET a returned artifacts.redline.download_url or artifacts.report.download_url with the same session. Use the supplied filename and expiry. HEAD requests and retries do not consume the download.
upload_id=<returned upload ID>
playbook_id=nda
risk_rating=low
leverage_rating=medium
markup_author=Customer
review_context=Purpose and points to focus on
confirm_replace=true

Obtain the user's consent to AI processing before sending confirm_replace=true (a retained compatibility field; these isolated review jobs do not replace the active editor). Optional multipart fields include company_context, counterparty_change_request, JSON arrays support_upload_ids and supplier_modules, and a JSON object additional_context. For Supplier DPA, answer {"eu_personal_data":"yes"} or {"eu_personal_data":"no"}. Risk and leverage are explicit low/medium/high choices.

Status includes legal/commercial phase while pending, then separate internal-issue and negotiation-note counts and artifact metadata. Counts represent annotated clause threads, not raw Word comment records. Validation errors require corrected input; expired or unknown IDs require a new review; a 429 means wait and retry. No document HTML is returned by this status endpoint.

Important limits

Upload and download records are process-local and bounded. Uploads and downloads expire after 15 minutes; idle review jobs expire after one hour. A server restart invalidates outstanding review IDs and downloads, so you must start a new review.

PDF reviews are converted to Word. Formatting may differ from the original; use the original DOCX where available or the clean Word review report.

Return to Pīwakawaka